@k-l-lambda/lilylet 0.1.63 → 0.1.65

package/lib/source/lilylet/lilypondDecoder.js

@@ -0,0 +1,1223 @@
+/**
+ * LilyPond to Lilylet Decoder
+ *
+ * Converts LilyPond notation files to Lilylet document format using the lotus parser.
+ * This module is browser-compatible - it uses pre-compiled parser from lotus.
+ */
+// Import directly from the compiled lib directory to avoid ESM issues
+import * as lilyParser from "@k-l-lambda/lotus/lib/inc/lilyParser/index.js";
+// Import pre-compiled LilyPond parser (browser-compatible)
+// @ts-ignore - CommonJS module
+import * as lilypondParser from "@k-l-lambda/lotus/lib.browser/lib/lilyParser.js";
+import { Clef, StemDirection, Accidental, Phonet, ArticulationType, OrnamentType, DynamicType, HairpinType, PedalType, NavigationMarkType, Placement, } from "./types.js";
+// Phonet names mapping
+const PHONET_NAMES = {
+    0: Phonet.c,
+    1: Phonet.d,
+    2: Phonet.e,
+    3: Phonet.f,
+    4: Phonet.g,
+    5: Phonet.a,
+    6: Phonet.b,
+};
+// Alter value to accidental
+const ALTER_TO_ACCIDENTAL = {
+    [-2]: Accidental.doubleFlat,
+    [-1]: Accidental.flat,
+    [0]: Accidental.natural,
+    [1]: Accidental.sharp,
+    [2]: Accidental.doubleSharp,
+};
+// LilyPond clef names to Lilylet clef
+const LILYPOND_CLEF_MAP = {
+    treble: Clef.treble,
+    G: Clef.treble,
+    bass: Clef.bass,
+    F: Clef.bass,
+    alto: Clef.alto,
+    C: Clef.alto,
+};
+// Key signature fifths to pitch/accidental mapping
+const KEY_FIFTHS_MAP = {
+    [-7]: { pitch: Phonet.c, accidental: Accidental.flat, mode: 'major' },
+    [-6]: { pitch: Phonet.g, accidental: Accidental.flat, mode: 'major' },
+    [-5]: { pitch: Phonet.d, accidental: Accidental.flat, mode: 'major' },
+    [-4]: { pitch: Phonet.a, accidental: Accidental.flat, mode: 'major' },
+    [-3]: { pitch: Phonet.e, accidental: Accidental.flat, mode: 'major' },
+    [-2]: { pitch: Phonet.b, accidental: Accidental.flat, mode: 'major' },
+    [-1]: { pitch: Phonet.f, mode: 'major' },
+    [0]: { pitch: Phonet.c, mode: 'major' },
+    [1]: { pitch: Phonet.g, mode: 'major' },
+    [2]: { pitch: Phonet.d, mode: 'major' },
+    [3]: { pitch: Phonet.a, mode: 'major' },
+    [4]: { pitch: Phonet.e, mode: 'major' },
+    [5]: { pitch: Phonet.b, mode: 'major' },
+    [6]: { pitch: Phonet.f, accidental: Accidental.sharp, mode: 'major' },
+    [7]: { pitch: Phonet.c, accidental: Accidental.sharp, mode: 'major' },
+};
+// Articulation mapping from LilyPond
+const ARTICULATION_MAP = {
+    staccato: ArticulationType.staccato,
+    staccatissimo: ArticulationType.staccatissimo,
+    tenuto: ArticulationType.tenuto,
+    marcato: ArticulationType.marcato,
+    accent: ArticulationType.accent,
+    portato: ArticulationType.portato,
+};
+// Ornament mapping from LilyPond
+const ORNAMENT_MAP = {
+    trill: OrnamentType.trill,
+    turn: OrnamentType.turn,
+    mordent: OrnamentType.mordent,
+    prall: OrnamentType.prall,
+    fermata: OrnamentType.fermata,
+    shortfermata: OrnamentType.shortFermata,
+    arpeggio: OrnamentType.arpeggio,
+};
+// Dynamic regex and mapping
+const DYNAMIC_REGEX = /^[fpmrsz]+$/;
+const DYNAMIC_MAP = {
+    ppp: DynamicType.ppp,
+    pp: DynamicType.pp,
+    p: DynamicType.p,
+    mp: DynamicType.mp,
+    mf: DynamicType.mf,
+    f: DynamicType.f,
+    ff: DynamicType.ff,
+    fff: DynamicType.fff,
+    sfz: DynamicType.sfz,
+    rfz: DynamicType.rfz,
+};
+// Common tempo text words (from fprod corpus analysis)
+// Single words, lowercase for case-insensitive matching
+const TEMPO_WORDS = new Set([
+    // Basic tempo markings (Italian) - very slow to very fast
+    'grave', 'largo', 'larghetto', 'lento', 'adagio', 'adagietto',
+    'andante', 'andantino', 'moderato', 'allegretto', 'allegro',
+    'vivace', 'presto', 'prestissimo',
+    // Tempo modifiers
+    'molto', 'poco', 'più', 'meno', 'assai', 'con', 'moto', 'brio',
+    'ma', 'non', 'troppo', 'cantabile', 'sostenuto', 'espressivo',
+    'grazioso', 'maestoso', 'agitato', 'animato', 'tranquillo',
+    // Tempo changes
+    'tempo', 'primo',
+    'rit', 'ritard', 'ritardando', 'riten', 'ritenuto',
+    'rall', 'rallentando',
+    'accel', 'accelerando',
+    'allarg', 'allargando',
+    'calando', 'morendo', 'smorzando', 'smorz',
+    'rubato',
+]);
+// Check if text contains any tempo-related word (case-insensitive)
+const containsTempoWord = (text) => {
+    // Remove punctuation and split into words
+    const words = text.toLowerCase().replace(/[.,!?]/g, '').split(/\s+/);
+    return words.some(word => TEMPO_WORDS.has(word));
+};
+// Convert lotus Tempo to Lilylet Tempo
+const convertTempo = (lotusTempo) => {
+    if (!lotusTempo)
+        return undefined;
+    const tempo = {};
+    // Text (e.g., "Allegro")
+    if (lotusTempo.text) {
+        tempo.text = typeof lotusTempo.text === 'string'
+            ? lotusTempo.text
+            : extractTextFromObject(lotusTempo.text);
+    }
+    // Metronome mark (e.g., ♩ = 120)
+    if (lotusTempo.beatsPerMinute !== undefined && Number.isFinite(lotusTempo.beatsPerMinute)) {
+        tempo.bpm = lotusTempo.beatsPerMinute;
+        // Beat unit (note value)
+        if (lotusTempo.unit) {
+            tempo.beat = convertDuration(lotusTempo.unit);
+        }
+    }
+    // Return undefined if no meaningful tempo data
+    if (!tempo.text && !tempo.bpm) {
+        return undefined;
+    }
+    return tempo;
+};
+// Convert LilyPond pitch to Lilylet pitch
+const convertPitch = (phonetStep, alterValue, octave) => {
+    const phonet = PHONET_NAMES[phonetStep % 7];
+    const accidental = alterValue !== 0 ? ALTER_TO_ACCIDENTAL[alterValue] : undefined;
+    // Lotus parser absolute octave: 0 = C3, 1 = C4, 2 = C5
+    // Lilylet octave: 0 = C4, 1 = C5, -1 = C3
+    // Conversion: lilyletOctave = lotusAbsoluteOctave - 1
+    const lilyletOctave = octave - 1;
+    return {
+        phonet,
+        accidental,
+        octave: lilyletOctave,
+    };
+};
+// Convert LilyPond duration to Lilylet duration
+const convertDuration = (duration) => {
+    return {
+        division: Math.pow(2, duration.division),
+        dots: duration.dots || 0,
+    };
+};
+// Parse raw pitch string (e.g., "c'", "fis''", "bes,") to Pitch
+const parseRawPitch = (pitchStr) => {
+    if (!pitchStr)
+        return undefined;
+    // Match: base note (a-g), optional accidentals (is/es/isis/eses), optional octave marks ('/, or ,)
+    const match = pitchStr.match(/^([a-g])(isis|eses|is|es)?([',]*)$/);
+    if (!match)
+        return undefined;
+    const [, note, accidental, octaveMarks] = match;
+    // Map note to phonet
+    const phonetMap = {
+        c: Phonet.c, d: Phonet.d, e: Phonet.e, f: Phonet.f,
+        g: Phonet.g, a: Phonet.a, b: Phonet.b,
+    };
+    const phonet = phonetMap[note];
+    if (!phonet)
+        return undefined;
+    // Map accidental
+    const accidentalMap = {
+        is: Accidental.sharp,
+        es: Accidental.flat,
+        isis: Accidental.doubleSharp,
+        eses: Accidental.doubleFlat,
+    };
+    const acc = accidental ? accidentalMap[accidental] : undefined;
+    // Calculate octave from marks (default octave 0 = C4)
+    let octave = 0;
+    for (const mark of octaveMarks || '') {
+        if (mark === "'")
+            octave++;
+        else if (mark === ",")
+            octave--;
+    }
+    return { phonet, accidental: acc, octave };
+};
+// Parse raw duration object from tuplet body
+const parseRawDuration = (duration) => {
+    if (!duration)
+        return undefined;
+    const number = parseInt(duration.number, 10);
+    if (isNaN(number))
+        return undefined;
+    return {
+        division: number,
+        dots: duration.dots || 0,
+    };
+};
+// Convert raw Chord from tuplet body to NoteEvent
+const convertRawChord = (chord, defaultDuration) => {
+    if (!chord || chord.proto !== 'Chord')
+        return undefined;
+    const pitches = [];
+    for (const pitchElem of chord.pitches || []) {
+        const pitch = parseRawPitch(pitchElem.pitch);
+        if (pitch)
+            pitches.push(pitch);
+    }
+    if (pitches.length === 0)
+        return undefined;
+    const duration = parseRawDuration(chord.duration) || defaultDuration;
+    if (!duration)
+        return undefined;
+    return {
+        type: 'note',
+        pitches,
+        duration,
+    };
+};
+// Parse pitch name with accidental (e.g., "cf" -> { pitch: Phonet.c, accidental: Accidental.flat })
+const parsePitchName = (name) => {
+    if (!name || name.length === 0)
+        return undefined;
+    const phonetChar = name[0].toLowerCase();
+    const phonet = {
+        'c': Phonet.c, 'd': Phonet.d, 'e': Phonet.e, 'f': Phonet.f,
+        'g': Phonet.g, 'a': Phonet.a, 'b': Phonet.b
+    }[phonetChar];
+    if (!phonet)
+        return undefined;
+    const accidentalPart = name.slice(1);
+    let accidental;
+    if (accidentalPart === 's' || accidentalPart === 'is') {
+        accidental = Accidental.sharp;
+    }
+    else if (accidentalPart === 'ss' || accidentalPart === 'isis') {
+        accidental = Accidental.doubleSharp;
+    }
+    else if (accidentalPart === 'f' || accidentalPart === 'es') {
+        accidental = Accidental.flat;
+    }
+    else if (accidentalPart === 'ff' || accidentalPart === 'eses') {
+        accidental = Accidental.doubleFlat;
+    }
+    return { pitch: phonet, accidental };
+};
+// Convert key from context to KeySignature
+const convertKeySignature = (keyContext) => {
+    const args = keyContext?.args;
+    // Always parse from args to get correct pitch and mode
+    if (Array.isArray(args) && args.length >= 2) {
+        const pitchStr = args[0];
+        const modeStr = args[1];
+        const pitchInfo = parsePitchName(pitchStr);
+        if (pitchInfo) {
+            const mode = modeStr?.includes('minor') ? 'minor' : 'major';
+            return {
+                pitch: pitchInfo.pitch,
+                accidental: pitchInfo.accidental,
+                mode,
+            };
+        }
+    }
+    // Fallback to fifths lookup for compatibility (major keys only)
+    const fifths = keyContext?.key;
+    if (fifths !== undefined && KEY_FIFTHS_MAP[fifths]) {
+        const mapping = KEY_FIFTHS_MAP[fifths];
+        return {
+            pitch: mapping.pitch,
+            accidental: mapping.accidental,
+            mode: mapping.mode,
+        };
+    }
+    return undefined;
+};
+const parsePostEvents = (postEvents) => {
+    const marks = [];
+    let harmonyText;
+    if (!postEvents)
+        return { marks };
+    for (const event of postEvents) {
+        // String events
+        if (typeof event === 'string') {
+            if (event === '~') {
+                marks.push({ markType: 'tie', start: true });
+            }
+            else if (event === '(') {
+                marks.push({ markType: 'slur', start: true });
+            }
+            else if (event === ')') {
+                marks.push({ markType: 'slur', start: false });
+            }
+            continue;
+        }
+        // PostEvent objects
+        if (event && typeof event === 'object') {
+            const arg = event.arg;
+            // String articulation/ornament
+            if (typeof arg === 'string') {
+                const cleanArg = arg.replace(/^-/, '');
+                if (ARTICULATION_MAP[cleanArg]) {
+                    marks.push({ markType: 'articulation', type: ARTICULATION_MAP[cleanArg] });
+                }
+                else if (ORNAMENT_MAP[cleanArg]) {
+                    marks.push({ markType: 'ornament', type: ORNAMENT_MAP[cleanArg] });
+                }
+            }
+            // Fingering (number 1-5)
+            if (typeof arg === 'number' && arg >= 1 && arg <= 5) {
+                marks.push({ markType: 'fingering', finger: arg });
+            }
+            // Command (dynamics, hairpins, etc.)
+            if (arg && typeof arg === 'object' && 'cmd' in arg) {
+                const cmd = arg.cmd;
+                if (DYNAMIC_REGEX.test(cmd) && DYNAMIC_MAP[cmd]) {
+                    marks.push({ markType: 'dynamic', type: DYNAMIC_MAP[cmd] });
+                }
+                else if (cmd === '<') {
+                    marks.push({ markType: 'hairpin', type: HairpinType.crescendoStart });
+                }
+                else if (cmd === '>') {
+                    marks.push({ markType: 'hairpin', type: HairpinType.diminuendoStart });
+                }
+                else if (cmd === '!') {
+                    marks.push({ markType: 'hairpin', type: HairpinType.crescendoEnd }); // or diminuendoEnd
+                }
+                else if (cmd === 'sustainOn') {
+                    marks.push({ markType: 'pedal', type: PedalType.sustainOn });
+                }
+                else if (cmd === 'sustainOff') {
+                    marks.push({ markType: 'pedal', type: PedalType.sustainOff });
+                }
+                else if (cmd === 'coda') {
+                    marks.push({ markType: 'navigation', type: NavigationMarkType.coda });
+                }
+                else if (cmd === 'segno') {
+                    marks.push({ markType: 'navigation', type: NavigationMarkType.segno });
+                }
+                else if (cmd === '\\markup' || cmd === 'markup') {
+                    // Check if this is a harmony (chord symbol) - marked with \bold
+                    const harmony = extractHarmonyFromMarkup(arg.args);
+                    if (harmony) {
+                        harmonyText = harmony;
+                    }
+                    else {
+                        // Regular markup attached to note
+                        const text = extractTextFromObject(arg.args);
+                        if (text && !containsTempoWord(text)) {
+                            const direction = event.direction;
+                            const placement = direction === 'up' ? Placement.above :
+                                direction === 'down' ? Placement.below : undefined;
+                            marks.push({ markType: 'markup', content: text, placement });
+                        }
+                    }
+                }
+            }
+            // Handle markup command directly (proto: 'MarkupCommand')
+            if (arg && typeof arg === 'object' && arg.proto === 'MarkupCommand') {
+                // Check if this is a harmony (chord symbol) - marked with \bold
+                const harmony = extractHarmonyFromMarkup(arg.args);
+                if (harmony) {
+                    harmonyText = harmony;
+                }
+                else {
+                    const text = extractTextFromObject(arg.args);
+                    if (text && !containsTempoWord(text)) {
+                        const direction = event.direction;
+                        const placement = direction === 'up' ? Placement.above :
+                            direction === 'down' ? Placement.below : undefined;
+                        marks.push({ markType: 'markup', content: text, placement });
+                    }
+                }
+            }
+        }
+    }
+    return { marks, harmonyText };
+};
+// Parse a LilyPond document to measures
+const parseLilyDocument = (lilyDocument) => {
+    const measureMap = new Map();
+    const staffNames = [];
+    const interpreter = lilyDocument.interpret();
+    // Pre-compute partIndex for each track using staff-number-sequence heuristic.
+    // When staff numbers reset (decrease), a new part starts — this handles multi-PianoStaff
+    // scores where both pianos reuse the same staff names ("1" and "2").
+    // Scores that embed partIndex in the staff name ("1_1", "1_2", "2_1") are handled
+    // by parseStaffName; this heuristic only kicks in for plain numeric names.
+    let _seqPart = 1;
+    let _seqMaxStaff = 0;
+    const _trackPartIndices = interpreter.layoutMusic.musicTracks.map((track) => {
+        const staffName = track.contextDict?.Staff;
+        if (staffName && /^\d+_\d+$/.test(staffName)) {
+            // Staff name encodes partIndex explicitly — don't apply heuristic
+            return parseInt(staffName.split('_')[0], 10);
+        }
+        // PianoStaff is present (even as empty string "") when inside a grand-staff group;
+        // undefined means standalone instrument → different part from grand-staff tracks.
+        const hasPianoStaff = (track.contextDict?.PianoStaff !== undefined);
+        const staffNum = parseInt(staffName || '1', 10) || 1;
+        if (hasPianoStaff) {
+            // Grand-staff: new part if transitioning from standalone or staff resets
+            if (_seqMaxStaff > 0 && staffNum < _seqMaxStaff) {
+                _seqPart++;
+                _seqMaxStaff = 0;
+            }
+            else if (_seqMaxStaff === -1) {
+                // Transitioning from a standalone group
+                _seqPart++;
+                _seqMaxStaff = 0;
+            }
+            _seqMaxStaff = Math.max(_seqMaxStaff, staffNum);
+        }
+        else {
+            // Standalone: mark with -1 so next grand-staff group increments
+            _seqMaxStaff = -1;
+        }
+        return _seqPart;
+    });
+    interpreter.layoutMusic.musicTracks.forEach((track, vi) => {
+        const appendStaff = (staffName) => {
+            if (!staffNames.includes(staffName)) {
+                staffNames.push(staffName);
+            }
+        };
+        // Parse staff name to extract partIndex and staff number
+        // Format: "partIndex_staffIndex" (e.g., "1_1", "1_2", "2_1")
+        // Falls back to positional ordering for non-numeric names (e.g., "upper"→1, "lower"→2)
+        const parseStaffName = (name) => {
+            const match = name.match(/^(\d+)_(\d+)$/);
+            if (match) {
+                return { partIndex: parseInt(match[1], 10), staffNum: parseInt(match[2], 10) };
+            }
+            const num = parseInt(name, 10);
+            if (!isNaN(num)) {
+                return { partIndex: 1, staffNum: num };
+            }
+            // Non-numeric name: assign staffNum by order of first appearance in staffNames
+            appendStaff(name);
+            const idx = staffNames.indexOf(name);
+            return { partIndex: 1, staffNum: idx + 1 };
+        };
+        // Use track.contextDict.Staff as the authoritative staff name (from Staff definition)
+        // This won't be affected by \change Staff commands inside the track
+        const initialStaffName = track.contextDict?.Staff;
+        if (initialStaffName) {
+            appendStaff(initialStaffName);
+        }
+        // Empty string staff name ("") means unnamed staff — treat as staff 1 within its part
+        const parsedStaff = (initialStaffName != null && initialStaffName !== '')
+            ? parseStaffName(initialStaffName)
+            : { partIndex: 1, staffNum: 1 };
+        // Use these as fixed values for this track - don't update from context.staffName
+        const trackStaff = parsedStaff.staffNum;
+        // Use sequence-based partIndex (detects multi-PianoStaff via staff number reset)
+        const trackPartIndex = _trackPartIndices[vi] ?? parsedStaff.partIndex;
+        // Track emitted context events across measures for this voice
+        let lastKey = undefined; // Track value changes (key fifths)
+        let lastTimeSig = undefined; // Track value changes (as string for comparison)
+        let lastClef = undefined; // Track value changes
+        let lastOttava = undefined; // Track value changes
+        let lastStemDirection = undefined; // Track value changes
+        let partialEmitted = false; // Emit \partial context once per track
+        const context = new lilyParser.TrackContext(undefined, {
+            listener: (term, context) => {
+                const mi = term._measure;
+                if (mi === undefined)
+                    return;
+                if (!measureMap.has(mi)) {
+                    measureMap.set(mi, {
+                        key: null,
+                        timeSig: null,
+                        voices: [],
+                        partial: false,
+                    });
+                }
+                const measure = measureMap.get(mi);
+                // Initialize voice for this track (use fixed staff/part from track definition)
+                if (!measure.voices[vi]) {
+                    measure.voices[vi] = {
+                        staff: trackStaff,
+                        partIndex: trackPartIndex,
+                        events: [],
+                    };
+                }
+                const voice = measure.voices[vi];
+                // Update key/time/partial from context on music events
+                if (term instanceof lilyParser.MusicEvent ||
+                    term instanceof lilyParser.LilyTerms.StemDirection ||
+                    term instanceof lilyParser.LilyTerms.OctaveShift ||
+                    term instanceof lilyParser.LilyTerms.Change ||
+                    term instanceof lilyParser.LilyTerms.Partial) {
+                    if (context.key && measure.key === null) {
+                        measure.key = context.key.key;
+                    }
+                    if (context.time && measure.timeSig === null) {
+                        measure.timeSig = {
+                            numerator: context.time.value.numerator,
+                            denominator: context.time.value.denominator,
+                        };
+                    }
+                    if (context.partialDuration) {
+                        measure.partial = true;
+                    }
+                }
+                // Emit \partial context event when the Partial term fires (before partialDuration is cleared)
+                if (term instanceof lilyParser.LilyTerms.Partial && context.partialDuration && !partialEmitted) {
+                    const mag = context.partialDuration.magnitude;
+                    const WHOLE = 1920;
+                    let division = 1, dots = 0;
+                    for (const div of [1, 2, 4, 8, 16, 32, 64]) {
+                        const base = WHOLE / div;
+                        if (Math.abs(mag - base) < 1) {
+                            division = div;
+                            dots = 0;
+                            break;
+                        }
+                        if (Math.abs(mag - Math.round(base * 1.5)) < 1) {
+                            division = div;
+                            dots = 1;
+                            break;
+                        }
+                        if (Math.abs(mag - Math.round(base * 1.75)) < 1) {
+                            division = div;
+                            dots = 2;
+                            break;
+                        }
+                    }
+                    voice.events.push({ type: 'context', partial: { division, dots } });
+                    partialEmitted = true;
+                }
+                // Handle music events
+                if (term instanceof lilyParser.MusicEvent) {
+                    // Staff is fixed per track (from track definition)
+                    voice.staff = trackStaff;
+                    // Handle key context change (emit when value changes)
+                    if (context.key && context.key.key !== lastKey) {
+                        const key = convertKeySignature(context.key);
+                        if (key) {
+                            voice.events.push({
+                                type: 'context',
+                                key,
+                            });
+                            lastKey = context.key.key;
+                        }
+                    }
+                    // Handle time signature context change (emit when value changes)
+                    if (context.time) {
+                        const timeSigStr = `${context.time.value.numerator}/${context.time.value.denominator}`;
+                        if (timeSigStr !== lastTimeSig) {
+                            voice.events.push({
+                                type: 'context',
+                                time: {
+                                    numerator: context.time.value.numerator,
+                                    denominator: context.time.value.denominator,
+                                },
+                            });
+                            lastTimeSig = timeSigStr;
+                        }
+                    }
+                    // Handle clef context change (emit when value changes)
+                    if (context.clef) {
+                        const clef = LILYPOND_CLEF_MAP[context.clef.clefName];
+                        if (clef && clef !== lastClef) {
+                            voice.events.push({
+                                type: 'context',
+                                clef,
+                            });
+                            lastClef = clef;
+                        }
+                    }
+                    // Handle ottava (emit when value changes)
+                    if (context.octave != null) {
+                        const currentOttava = context.octave.value ?? 0;
+                        if (currentOttava !== lastOttava) {
+                            voice.events.push({
+                                type: 'context',
+                                ottava: currentOttava,
+                            });
+                            lastOttava = currentOttava;
+                        }
+                    }
+                    // Handle stem direction context change (emit when value changes)
+                    if (context.stemDirection && context.stemDirection !== lastStemDirection) {
+                        const stemDir = context.stemDirection === 'Up' ? StemDirection.up :
+                            context.stemDirection === 'Down' ? StemDirection.down : undefined;
+                        if (stemDir) {
+                            voice.events.push({
+                                type: 'context',
+                                stemDirection: stemDir,
+                            });
+                            lastStemDirection = context.stemDirection;
+                        }
+                    }
+                    // Process Chord (note or chord, or positioned rest if isRest)
+                    if (term instanceof lilyParser.LilyTerms.Chord) {
+                        const pitches = [];
+                        for (const pitch of term.pitchesValue) {
+                            if (pitch instanceof lilyParser.LilyTerms.ChordElement) {
+                                pitches.push(convertPitch(pitch.phonetStep, pitch.alterValue || 0, pitch.absolutePitch.octave));
+                            }
+                        }
+                        if (pitches.length > 0) {
+                            // Check if this is a positioned rest (a\rest syntax)
+                            if (term.isRest) {
+                                const restEvent = {
+                                    type: 'rest',
+                                    duration: convertDuration(term.durationValue),
+                                    pitch: pitches[0], // Use first pitch for positioning
+                                };
+                                voice.events.push(restEvent);
+                            }
+                            else {
+                                const { marks, harmonyText } = parsePostEvents(term.post_events);
+                                // Add beam marks
+                                if (term.beamOn) {
+                                    marks.push({ markType: 'beam', start: true });
+                                }
+                                else if (term.beamOff) {
+                                    marks.push({ markType: 'beam', start: false });
+                                }
+                                // Add tie
+                                if (term.isTying) {
+                                    marks.push({ markType: 'tie', start: true });
+                                }
+                                const noteEvent = {
+                                    type: 'note',
+                                    pitches,
+                                    duration: convertDuration(term.durationValue),
+                                    grace: context.inGrace || undefined,
+                                };
+                                if (marks.length > 0) {
+                                    noteEvent.marks = marks;
+                                }
+                                voice.events.push(noteEvent);
+                                // Add harmony event if detected (chord symbol encoded as \bold markup)
+                                if (harmonyText) {
+                                    const harmonyEvent = {
+                                        type: 'harmony',
+                                        text: harmonyText,
+                                    };
+                                    voice.events.push(harmonyEvent);
+                                }
+                            }
+                        }
+                    }
+                    // Process Rest
+                    else if (term instanceof lilyParser.LilyTerms.Rest) {
+                        // Ignore spacer rests inside grace contexts (e.g. \acciaccatura s8,
+                        // \grace s4 — these are notation-only placeholders with no musical content)
+                        if (!(term.isSpacer && context.inGrace)) {
+                            const restEvent = {
+                                type: 'rest',
+                                duration: convertDuration(term.durationValue),
+                                fullMeasure: (term.name === 'R') || undefined,
+                                invisible: term.isSpacer || undefined,
+                            };
+                            voice.events.push(restEvent);
+                        }
+                    }
+                }
+                // Handle standalone stem direction (emit when value changes)
+                else if (term instanceof lilyParser.LilyTerms.StemDirection) {
+                    if (term.direction !== lastStemDirection) {
+                        const stemDir = term.direction === 'Up' ? StemDirection.up :
+                            term.direction === 'Down' ? StemDirection.down : undefined;
+                        if (stemDir) {
+                            voice.events.push({
+                                type: 'context',
+                                stemDirection: stemDir,
+                            });
+                            lastStemDirection = term.direction;
+                        }
+                    }
+                }
+                // Handle standalone clef (emit when value changes)
+                else if (term instanceof lilyParser.LilyTerms.Clef) {
+                    const clef = LILYPOND_CLEF_MAP[term.clefName];
+                    if (clef && clef !== lastClef) {
+                        voice.events.push({
+                            type: 'context',
+                            clef,
+                        });
+                        lastClef = clef;
+                    }
+                }
+                // Handle ottava shift
+                else if (term instanceof lilyParser.LilyTerms.OctaveShift) {
+                    if (term.value !== lastOttava) {
+                        voice.events.push({
+                            type: 'context',
+                            ottava: term.value,
+                        });
+                        lastOttava = term.value;
+                    }
+                }
+                // Handle staff change (\change Staff = "N")
+                // args[0] is Assignment { key: "Staff", value: { exp: '"N"' } }
+                else if (term instanceof lilyParser.LilyTerms.Change) {
+                    const assignment = term.args?.[0];
+                    if (assignment?.key === 'Staff') {
+                        // exp is like '"2"' — strip surrounding quotes then parse strictly
+                        const exp = assignment?.value?.exp ?? '';
+                        const raw = exp.replace(/^"|"$/g, '');
+                        // Only accept pure integer staff names (e.g. "1", "2")
+                        // Reject compound names like "1_2", "RH", "LH"
+                        const staffNum = /^\d+$/.test(raw) ? parseInt(raw, 10) : NaN;
+                        if (!isNaN(staffNum)) {
+                            voice.events.push({ type: 'context', staff: staffNum });
+                        }
+                    }
+                }
+                // Handle tempo
+                else if (term instanceof lilyParser.LilyTerms.Tempo) {
+                    const tempo = convertTempo(term);
+                    if (tempo) {
+                        voice.events.push({
+                            type: 'context',
+                            tempo,
+                        });
+                    }
+                }
+                // Handle standalone markup command and barlines
+                else {
+                    const termAny = term;
+                    if (termAny.proto === 'Command' && (termAny.cmd === '\\markup' || termAny.cmd === 'markup')) {
+                        // Check if this is a harmony (chord symbol) - marked with \bold
+                        const harmonyText = extractHarmonyFromMarkup(termAny.args);
+                        if (harmonyText) {
+                            const harmonyEvent = {
+                                type: 'harmony',
+                                text: harmonyText,
+                            };
+                            voice.events.push(harmonyEvent);
+                        }
+                        else {
+                            const text = extractTextFromObject(termAny.args);
+                            if (text && !containsTempoWord(text)) {
+                                const markupEvent = {
+                                    type: 'markup',
+                                    content: text,
+                                };
+                                voice.events.push(markupEvent);
+                            }
+                        }
+                    }
+                    // Handle barline command - barlines belong to the previous measure
+                    else if (termAny.proto === 'Command' && termAny.cmd === 'bar') {
+                        const style = termAny.args?.[0]?.exp;
+                        if (style && mi > 0) {
+                            // Remove quotes from the style string
+                            const barStyle = style.replace(/^"|"$/g, '');
+                            // Add to previous measure's voice
+                            const prevMeasure = measureMap.get(mi - 1);
+                            if (prevMeasure && prevMeasure.voices[vi]) {
+                                prevMeasure.voices[vi].events.push({
+                                    type: 'barline',
+                                    style: barStyle,
+                                });
+                            }
+                        }
+                    }
+                    // Handle ChordSymbol (inline chord symbol: \chords "text")
+                    else if (termAny.proto === 'ChordSymbol') {
+                        // Extract text from LiteralString (e.g., { exp: '"C"' } -> "C")
+                        let text = termAny.text;
+                        if (typeof text === 'object' && text?.exp) {
+                            text = text.exp.replace(/^"|"$/g, '');
+                        }
+                        else if (typeof text === 'string') {
+                            text = text.replace(/^"|"$/g, '');
+                        }
+                        const harmonyEvent = {
+                            type: 'harmony',
+                            text: text,
+                        };
+                        voice.events.push(harmonyEvent);
+                    }
+                    // Handle tuplet
+                    // Note: Lotus emits Chord events BEFORE the Tuplet term, so we need to
+                    // remove the already-added notes and wrap them in a TupletEvent
+                    else if (termAny.proto === 'Tuplet' || termAny.proto === 'Times') {
+                        const isTimes = termAny.proto === 'Times';
+                        const ratioStr = termAny.args?.[0]; // "3/2" for \tuplet, "2/3" for \times
+                        // \tuplet supports an optional base-duration arg: \tuplet 3/2 4 { notes }
+                        // making args = [ratio, baseDur?, body]. Use the last arg (= music block),
+                        // matching what lotus Tuplet.music getter does: this.args[this.args.length-1]
+                        const body = termAny.args?.[termAny.args.length - 1]?.body || [];
+                        if (ratioStr && body.length > 0) {
+                            const ratioMatch = ratioStr.match(/^(\d+)\/(\d+)$/);
+                            if (ratioMatch) {
+                                const [, num, denom] = ratioMatch;
+                                // \tuplet 3/2: divider = 3/2, lilylet ratio = 2/3 → swap
+                                // \times 2/3: factor = 2/3, lilylet ratio = 2/3 → no swap
+                                const ratio = isTimes
+                                    ? { numerator: parseInt(num, 10), denominator: parseInt(denom, 10) }
+                                    : { numerator: parseInt(denom, 10), denominator: parseInt(num, 10) };
+                                // Count sounding (non-grace) notes/rests in the tuplet body,
+                                // recursing into AfterGrace.body (main note) but not AfterGrace.grace.
+                                // Grace / Acciaccatura / Appoggiatura blocks count as 0.
+                                const countSounding = (items) => {
+                                    let n = 0;
+                                    for (const item of items) {
+                                        if (!item)
+                                            continue;
+                                        switch (item.proto) {
+                                            case 'Chord':
+                                            case 'Rest':
+                                                n++;
+                                                break;
+                                            case 'AfterGrace': {
+                                                // args[0] = main note, args[1] = after-grace notes (0-dur, skip)
+                                                const main = item.args?.[0];
+                                                if (main?.proto === 'Chord' || main?.proto === 'Rest')
+                                                    n++;
+                                                else if (main?.body)
+                                                    n += countSounding(main.body);
+                                                break;
+                                            }
+                                            case 'Grace':
+                                            case 'Acciaccatura':
+                                            case 'Appoggiatura': break;
+                                            default:
+                                                if (item.body)
+                                                    n += countSounding(item.body);
+                                                break;
+                                        }
+                                    }
+                                    return n;
+                                };
+                                const noteCount = countSounding(body);
+                                const tupletEvents = [];
+                                let removed = 0;
+                                // Pop notes/rests from voice.events, skipping context events.
+                                // Grace notes are moved inside the tuplet but do NOT consume a
+                                // sounding-note slot (they have 0 duration in the time signature).
+                                while (removed < noteCount && voice.events.length > 0) {
+                                    const lastEvent = voice.events[voice.events.length - 1];
+                                    if (lastEvent.type === 'note' || lastEvent.type === 'rest') {
+                                        tupletEvents.unshift(voice.events.pop());
+                                        if (!lastEvent.grace)
+                                            removed++;
+                                    }
+                                    else if (lastEvent.type === 'context' || lastEvent.type === 'pitchReset') {
+                                        // Context event between tuplet notes — move it inside tuplet too
+                                        tupletEvents.unshift(voice.events.pop());
+                                    }
+                                    else {
+                                        break;
+                                    }
+                                }
+                                if (tupletEvents.length > 0) {
+                                    voice.events.push(isTimes
+                                        ? { type: 'times', ratio, events: tupletEvents }
+                                        : { type: 'tuplet', ratio, events: tupletEvents });
+                                }
+                            }
+                        }
+                    }
+                    // Handle repeat tremolo
+                    else if (termAny.proto === 'Repeat' && termAny.args?.[0] === 'tremolo') {
+                        const count = parseInt(termAny.args?.[1], 10);
+                        const body = termAny.args?.[2]?.body || [];
+                        if (!isNaN(count) && body.length === 2) {
+                            // Double tremolo has exactly 2 pitches
+                            const pitch1 = body[0]?.pitches?.[0]?.pitch;
+                            const pitch2 = body[1]?.pitches?.[0]?.pitch;
+                            const duration = body[0]?.duration;
+                            if (pitch1 && pitch2 && duration) {
+                                const pitchA = parseRawPitch(pitch1);
+                                const pitchB = parseRawPitch(pitch2);
+                                const div = parseInt(duration.number, 10);
+                                if (pitchA && pitchB && !isNaN(div)) {
+                                    // Remove the 2 notes that were already added
+                                    let removed = 0;
+                                    while (removed < 2 && voice.events.length > 0) {
+                                        const lastEvent = voice.events[voice.events.length - 1];
+                                        if (lastEvent.type === 'note') {
+                                            voice.events.pop();
+                                            removed++;
+                                        }
+                                        else {
+                                            break;
+                                        }
+                                    }
+                                    const tremoloEvent = {
+                                        type: 'tremolo',
+                                        pitchA: [pitchA],
+                                        pitchB: [pitchB],
+                                        count,
+                                        division: div,
+                                    };
+                                    voice.events.push(tremoloEvent);
+                                }
+                            }
+                        }
+                    }
+                }
+            },
+        });
+        context.execute(track.music);
+        // Post-process: carry staff state across measure boundaries for this voice.
+        // If measure N ends on staff 2 (via \change Staff), measure N+1 must begin
+        // with context { staff: 2 } so notes at the start of that measure serialize
+        // on the correct staff.
+        {
+            const measureIndices = Array.from(measureMap.keys()).sort((a, b) => a - b);
+            let carryStaff = trackStaff;
+            for (const mi of measureIndices) {
+                const voice = measureMap.get(mi)?.voices[vi];
+                if (!voice)
+                    continue;
+                // Prepend carry-over event if previous measure ended on a different staff,
+                // but skip if the voice's first explicit staff event already resets to
+                // trackStaff — the carry-over would be immediately cancelled (no-op).
+                if (carryStaff !== trackStaff) {
+                    // Suppress carry-over if the first staff event resets to trackStaff
+                    // AND no musical events (notes/rests/etc.) precede it — meaning the
+                    // carry-over would be immediately cancelled with no effect.
+                    const firstStaffCtxIdx = voice.events.findIndex(e => e.type === 'context' && e.staff != null);
+                    const musicalTypes = new Set(['note', 'rest', 'tuplet', 'times', 'tremolo']);
+                    const hasMusicBeforeFirstStaff = firstStaffCtxIdx > 0 &&
+                        voice.events.slice(0, firstStaffCtxIdx).some(e => musicalTypes.has(e.type));
+                    const immediatelyCancelled = firstStaffCtxIdx >= 0 &&
+                        voice.events[firstStaffCtxIdx].staff === trackStaff &&
+                        !hasMusicBeforeFirstStaff;
+                    if (!immediatelyCancelled) {
+                        voice.events.unshift({ type: 'context', staff: carryStaff });
+                    }
+                }
+                // Update carryStaff from this measure's events (including inside tuplets)
+                const scanStaff = (events) => {
+                    for (const e of events) {
+                        if (e.type === 'context' && e.staff) {
+                            carryStaff = e.staff;
+                        }
+                        else if ((e.type === 'tuplet' || e.type === 'times') && e.events) {
+                            scanStaff(e.events);
+                        }
+                    }
+                };
+                scanStaff(voice.events);
+            }
+        }
+    });
+    // Filter out empty voices and convert to array, sorted by measure number
+    const measures = Array.from(measureMap.entries())
+        .sort(([a], [b]) => a - b)
+        .map(([, measure]) => measure);
+    for (const measure of measures) {
+        measure.voices = measure.voices.filter(Boolean);
+    }
+    return measures;
+};
+// Check if a voice has real music content (not just spacer rests and context changes)
+const hasRealContent = (events) => {
+    return events.some(e => {
+        if (e.type === 'note')
+            return true;
+        if (e.type === 'rest' && !e.invisible)
+            return true;
+        if (e.type === 'tuplet')
+            return true;
+        if (e.type === 'times')
+            return true;
+        if (e.type === 'tremolo')
+            return true;
+        return false;
+    });
+};
+// Remove quotes from string literal
+const unquoteString = (str) => {
+    if (str.startsWith('"') && str.endsWith('"')) {
+        return str.slice(1, -1);
+    }
+    return str;
+};
+// Extract text from lotus parser objects recursively
+const extractTextFromObject = (obj) => {
+    if (!obj)
+        return undefined;
+    // Simple string
+    if (typeof obj === 'string') {
+        return obj;
+    }
+    // Array - concatenate all text
+    if (Array.isArray(obj)) {
+        const texts = [];
+        for (const item of obj) {
+            const text = extractTextFromObject(item);
+            if (text)
+                texts.push(text);
+        }
+        return texts.join(' ').trim() || undefined;
+    }
+    // Object with proto property (lotus parser objects)
+    if (obj && typeof obj === 'object' && obj.proto) {
+        switch (obj.proto) {
+            case 'LiteralString':
+                // exp contains quoted string like '"Hello"'
+                if (obj.exp) {
+                    return unquoteString(obj.exp);
+                }
+                break;
+            case 'MarkupCommand':
+            case 'Command':
+                // Recursively extract from args
+                if (obj.args) {
+                    return extractTextFromObject(obj.args);
+                }
+                break;
+            case 'InlineBlock':
+                // Extract from body, skip primitive commands
+                if (obj.body) {
+                    const texts = [];
+                    for (const item of obj.body) {
+                        if (item.proto !== 'Primitive') {
+                            const text = extractTextFromObject(item);
+                            if (text)
+                                texts.push(text);
+                        }
+                    }
+                    return texts.join(' ').trim() || undefined;
+                }
+                break;
+            case 'String':
+                if (obj.value) {
+                    return obj.value;
+                }
+                break;
+        }
+    }
+    // Fallback: try value property
+    if (obj.value !== undefined) {
+        return extractTextFromObject(obj.value);
+    }
+    return undefined;
+};
+// Check if markup contains \bold command (indicates harmony/chord symbol)
+// Returns the text if it's a harmony, undefined otherwise
+const extractHarmonyFromMarkup = (obj) => {
+    if (!obj)
+        return undefined;
+    // Check array of args
+    if (Array.isArray(obj)) {
+        for (const item of obj) {
+            const result = extractHarmonyFromMarkup(item);
+            if (result !== undefined)
+                return result;
+        }
+        return undefined;
+    }
+    if (obj && typeof obj === 'object') {
+        // Check if this is a \bold command (can be Command or MarkupCommand)
+        if ((obj.proto === 'Command' || obj.proto === 'MarkupCommand') &&
+            (obj.cmd === 'bold' || obj.cmd === '\\bold')) {
+            // Extract the text from args
+            return extractTextFromObject(obj.args);
+        }
+        // Recursively search InlineBlock body
+        if (obj.proto === 'InlineBlock' && obj.body) {
+            return extractHarmonyFromMarkup(obj.body);
+        }
+        // Recursively search args
+        if (obj.args) {
+            return extractHarmonyFromMarkup(obj.args);
+        }
+    }
+    return undefined;
+};
+// Extract string value from header field
+const extractStringValue = (value) => {
+    const text = extractTextFromObject(value);
+    return text ? text.trim() : undefined;
+};
+// Extract metadata from LilyDocument
+const extractMetadata = (lilyDocument) => {
+    try {
+        const attrs = lilyDocument.globalAttributesReadOnly();
+        const metadata = {};
+        // Extract each field, handling markup structures
+        if (attrs.title) {
+            metadata.title = extractStringValue(attrs.title);
+        }
+        if (attrs.subtitle) {
+            metadata.subtitle = extractStringValue(attrs.subtitle);
+        }
+        if (attrs.composer) {
+            metadata.composer = extractStringValue(attrs.composer);
+        }
+        if (attrs.arranger) {
+            metadata.arranger = extractStringValue(attrs.arranger);
+        }
+        if (attrs.poet) {
+            metadata.lyricist = extractStringValue(attrs.poet);
+        }
+        if (attrs.opus) {
+            metadata.opus = extractStringValue(attrs.opus);
+        }
+        if (attrs.instrument) {
+            metadata.instrument = extractStringValue(attrs.instrument);
+        }
+        // Return undefined if no metadata fields were populated
+        if (Object.keys(metadata).length === 0) {
+            return undefined;
+        }
+        return metadata;
+    }
+    catch (e) {
+        // If metadata extraction fails, continue without it
+        return undefined;
+    }
+};
+// Dedupe consecutive context events in merged voice
+// This is needed because multiple tracks merged into one voice may have redundant context events
+const dedupeContextEvents = (events) => {
+    const result = [];
+    let lastStemDirection;
+    let lastClef;
+    for (const e of events) {
+        if (e.type === 'context') {
+            const ctx = e;
+            // Dedupe stemDirection
+            if ('stemDirection' in ctx) {
+                if (ctx.stemDirection === lastStemDirection)
+                    continue;
+                lastStemDirection = ctx.stemDirection;
+            }
+            // Dedupe clef
+            if ('clef' in ctx) {
+                if (ctx.clef === lastClef)
+                    continue;
+                lastClef = ctx.clef;
+            }
+        }
+        result.push(e);
+    }
+    return result;
+};
+// Convert parsed measures to LilyletDoc
+const parsedMeasuresToDoc = (parsedMeasures, metadata) => {
+    const measures = parsedMeasures.map(pm => {
+        // Filter out voices that only contain spacer rests and context changes
+        const filteredVoices = pm.voices.filter(v => hasRealContent(v.events));
+        // Group voices by partIndex, then collect voice arrays per staff
+        const partMap = new Map();
+        for (const v of filteredVoices) {
+            const pi = v.partIndex || 1;
+            if (!partMap.has(pi)) {
+                partMap.set(pi, new Map());
+            }
+            const staffMap = partMap.get(pi);
+            // Preserve each voice as a separate array
+            if (!staffMap.has(v.staff)) {
+                staffMap.set(v.staff, []);
+            }
+            staffMap.get(v.staff).push(v.events);
+        }
+        // Convert to parts array (sorted by part index, then by staff)
+        // Apply deduplication to each voice's events
+        const partIndices = Array.from(partMap.keys()).sort((a, b) => a - b);
+        const parts = partIndices.map(pi => {
+            const staffMap = partMap.get(pi);
+            const staffNums = Array.from(staffMap.keys()).sort((a, b) => a - b);
+            return {
+                voices: staffNums.flatMap(staff => staffMap.get(staff).map(events => ({
+                    staff,
+                    events: dedupeContextEvents(events),
+                }))),
+            };
+        });
+        // Fallback to single empty part if no voices
+        const measure = {
+            parts: parts.length > 0 ? parts : [{ voices: [] }],
+        };
+        if (pm.key !== null) {
+            measure.key = convertKeySignature(pm.key);
+        }
+        if (pm.timeSig) {
+            measure.timeSig = pm.timeSig;
+        }
+        if (pm.partial) {
+            measure.partial = true;
+        }
+        return measure;
+    })
+        // Filter out empty measures (no voices in any part)
+        .filter(m => m.parts.some(p => p.voices.length > 0));
+    const doc = { measures };
+    if (metadata) {
+        doc.metadata = metadata;
+    }
+    return doc;
+};
+/**
+ * Decode a LilyPond string to LilyletDoc (synchronous, browser-compatible)
+ */
+const decode = (lilypondSource) => {
+    const rawData = lilypondParser.parse(lilypondSource);
+    const lilyDocument = new lilyParser.LilyDocument(rawData);
+    const parsedMeasures = parseLilyDocument(lilyDocument);
+    const metadata = extractMetadata(lilyDocument);
+    return parsedMeasuresToDoc(parsedMeasures, metadata);
+};
+/**
+ * Decode from pre-parsed LilyDocument (synchronous, for when you already have parsed data)
+ */
+const decodeFromDocument = (lilyDocument) => {
+    const parsedMeasures = parseLilyDocument(lilyDocument);
+    const metadata = extractMetadata(lilyDocument);
+    return parsedMeasuresToDoc(parsedMeasures, metadata);
+};
+export { decode, decodeFromDocument, parseLilyDocument, };