@k-l-lambda/lilylet 0.1.62 → 0.1.64

package/lib/source/lilylet/serializer.js

@@ -0,0 +1,791 @@
+/**
+ * Lilylet Document Serializer
+ *
+ * Converts LilyletDoc to Lilylet (.lyl) string format.
+ * Uses relative pitch mode matching the parser's behavior.
+ */
+import { StemDirection, } from "./types.js";
+const PHONETS = "cdefgab";
+/**
+ * Calculate the octave markers needed to serialize a pitch in relative mode.
+ *
+ * The parser logic:
+ * - Calculate interval from previous pitch
+ * - If |interval| > 3, adjust octave (go the "short way")
+ * - Add explicit ' and , markers from the pitch
+ *
+ * We need to reverse this: given the target absolute octave,
+ * calculate what markers are needed.
+ */
+const getRelativeOctaveMarkers = (env, pitch) => {
+    const step = PHONETS.indexOf(pitch.phonet);
+    if (step === -1) {
+        return { markers: '', newEnv: env };
+    }
+    const interval = step - env.step;
+    // Parser's octave adjustment calculation
+    const octInc = Math.floor(Math.abs(interval) / 4) * -Math.sign(interval);
+    // Without any markers, parser would calculate:
+    // env.octave + 0 (marker) + octInc = base octave
+    const baseOctave = env.octave + octInc;
+    // We need markers to reach pitch.octave from baseOctave
+    const markerCount = pitch.octave - baseOctave;
+    let markers = '';
+    if (markerCount > 0) {
+        markers = "'".repeat(markerCount);
+    }
+    else if (markerCount < 0) {
+        markers = ",".repeat(-markerCount);
+    }
+    // Update environment (mirrors parser behavior)
+    const newEnv = {
+        step: step,
+        octave: pitch.octave
+    };
+    return { markers, newEnv };
+};
+// Accidental to Lilylet notation
+const ACCIDENTAL_MAP = {
+    natural: '!',
+    sharp: 's',
+    flat: 'f',
+    doubleSharp: 'ss',
+    doubleFlat: 'ff',
+};
+// Clef to Lilylet notation
+const CLEF_MAP = {
+    treble: 'treble',
+    bass: 'bass',
+    alto: 'alto',
+};
+// Articulation to Lilylet notation
+const ARTICULATION_MAP = {
+    staccato: '.',
+    staccatissimo: '!',
+    tenuto: '_',
+    marcato: '^',
+    accent: '>',
+    portato: '_.',
+};
+// Ornament to Lilylet notation
+const ORNAMENT_MAP = {
+    trill: '\\trill',
+    turn: '\\turn',
+    mordent: '\\mordent',
+    prall: '\\prall',
+    fermata: '\\fermata',
+    shortFermata: '\\shortfermata',
+    arpeggio: '\\arpeggio',
+};
+// Dynamic to Lilylet notation
+const DYNAMIC_MAP = {
+    ppp: '\\ppp',
+    pp: '\\pp',
+    p: '\\p',
+    mp: '\\mp',
+    mf: '\\mf',
+    f: '\\f',
+    ff: '\\ff',
+    fff: '\\fff',
+    sfz: '\\sfz',
+    rfz: '\\rfz',
+    fp: '\\fp',
+};
+// Hairpin to Lilylet notation
+const HAIRPIN_MAP = {
+    crescendoStart: '\\<',
+    crescendoEnd: '\\!',
+    diminuendoStart: '\\>',
+    diminuendoEnd: '\\!',
+};
+// Pedal to Lilylet notation
+const PEDAL_MAP = {
+    sustainOn: '\\sustainOn',
+    sustainOff: '\\sustainOff',
+    sostenutoOn: '\\sostenutoOn',
+    sostenutoOff: '\\sostenutoOff',
+    unaCordaOn: '\\unaCorda',
+    unaCordaOff: '\\treCorde',
+};
+// Serialize a pitch to Lilylet notation (absolute mode - for contexts like key signature)
+const serializePitchAbsolute = (pitch) => {
+    let result = String(pitch.phonet);
+    // Add accidental
+    if (pitch.accidental) {
+        result += ACCIDENTAL_MAP[pitch.accidental] || '';
+    }
+    // Add octave markers
+    if (pitch.octave > 0) {
+        result += "'".repeat(pitch.octave);
+    }
+    else if (pitch.octave < 0) {
+        result += ",".repeat(-pitch.octave);
+    }
+    return result;
+};
+// Serialize a pitch in relative mode
+const serializePitchRelative = (pitch, env) => {
+    let result = String(pitch.phonet);
+    // Add accidental
+    if (pitch.accidental) {
+        result += ACCIDENTAL_MAP[pitch.accidental] || '';
+    }
+    // Calculate relative octave markers
+    const { markers, newEnv } = getRelativeOctaveMarkers(env, pitch);
+    result += markers;
+    return { str: result, newEnv };
+};
+// Serialize duration to Lilylet notation
+const serializeDuration = (duration) => {
+    let result = duration.division.toString();
+    // Add dots
+    if (duration.dots > 0) {
+        result += '.'.repeat(duration.dots);
+    }
+    return result;
+};
+// Serialize marks (articulations, ornaments, dynamics, etc.)
+const serializeMarks = (marks) => {
+    const parts = [];
+    for (const mark of marks) {
+        switch (mark.markType) {
+            case 'tie':
+                if (mark.start)
+                    parts.push('~');
+                break;
+            case 'slur':
+                parts.push(mark.start ? '(' : ')');
+                break;
+            case 'beam':
+                parts.push(mark.start ? '[' : ']');
+                break;
+            case 'articulation': {
+                const artStr = ARTICULATION_MAP[mark.type];
+                if (artStr) {
+                    const prefix = mark.placement === 'above' ? '^' : mark.placement === 'below' ? '_' : '-';
+                    parts.push(prefix + artStr);
+                }
+                break;
+            }
+            case 'ornament': {
+                const ornStr = ORNAMENT_MAP[mark.type];
+                if (ornStr)
+                    parts.push(ornStr);
+                break;
+            }
+            case 'dynamic': {
+                const dynStr = DYNAMIC_MAP[mark.type];
+                if (dynStr)
+                    parts.push(dynStr);
+                break;
+            }
+            case 'hairpin': {
+                const hairpinStr = HAIRPIN_MAP[mark.type];
+                if (hairpinStr)
+                    parts.push(hairpinStr);
+                break;
+            }
+            case 'pedal': {
+                const pedalStr = PEDAL_MAP[mark.type];
+                if (pedalStr)
+                    parts.push(pedalStr);
+                break;
+            }
+            case 'fingering':
+                parts.push('-' + mark.finger);
+                break;
+        }
+    }
+    return parts.join('');
+};
+// Serialize a note event with pitch environment tracking
+const serializeNoteEvent = (event, env, prevDuration) => {
+    const parts = [];
+    let currentEnv = env;
+    // Grace note prefix
+    if (event.grace) {
+        parts.push('\\grace ');
+    }
+    // Single note or chord
+    if (event.pitches.length === 1) {
+        const { str, newEnv } = serializePitchRelative(event.pitches[0], currentEnv);
+        parts.push(str);
+        currentEnv = newEnv;
+    }
+    else if (event.pitches.length > 1) {
+        // Chord: <c e g>
+        // First pitch is relative to previous note, subsequent pitches relative to each other
+        const pitchStrs = [];
+        const { str: firstStr, newEnv: firstEnv } = serializePitchRelative(event.pitches[0], currentEnv);
+        pitchStrs.push(firstStr);
+        currentEnv = firstEnv;
+        // Chord pitches are relative to each other within the chord
+        let chordEnv = { ...currentEnv };
+        for (let i = 1; i < event.pitches.length; i++) {
+            const { str, newEnv } = serializePitchRelative(event.pitches[i], chordEnv);
+            pitchStrs.push(str);
+            chordEnv = newEnv;
+        }
+        parts.push('<' + pitchStrs.join(' ') + '>');
+    }
+    // Duration (only if different from previous or first note)
+    const durStr = serializeDuration(event.duration);
+    if (!prevDuration ||
+        prevDuration.division !== event.duration.division ||
+        prevDuration.dots !== event.duration.dots) {
+        parts.push(durStr);
+    }
+    // Tremolo
+    if (event.tremolo) {
+        parts.push(':' + event.tremolo);
+    }
+    // Marks
+    if (event.marks && event.marks.length > 0) {
+        parts.push(serializeMarks(event.marks));
+    }
+    return { str: parts.join(''), newEnv: currentEnv };
+};
+// Serialize a rest event with pitch environment tracking
+const serializeRestEvent = (event, env, prevDuration) => {
+    const parts = [];
+    let currentEnv = env;
+    let isPitchedRest = false;
+    // Full measure rest
+    if (event.fullMeasure) {
+        parts.push('R');
+    }
+    // Space rest (invisible)
+    else if (event.invisible) {
+        parts.push('s');
+    }
+    // Positioned rest: pitch + duration + \rest
+    else if (event.pitch) {
+        const { str, newEnv } = serializePitchRelative(event.pitch, currentEnv);
+        parts.push(str);
+        currentEnv = newEnv;
+        isPitchedRest = true;
+    }
+    else {
+        parts.push('r');
+    }
+    // Duration
+    const durStr = serializeDuration(event.duration);
+    if (!prevDuration ||
+        prevDuration.division !== event.duration.division ||
+        prevDuration.dots !== event.duration.dots) {
+        parts.push(durStr);
+    }
+    // \rest mark comes after duration for positioned rests
+    if (isPitchedRest) {
+        parts.push('\\rest');
+    }
+    return { str: parts.join(''), newEnv: currentEnv };
+};
+// Serialize a context change
+const serializeContextChange = (event) => {
+    const parts = [];
+    // Clef
+    if (event.clef) {
+        parts.push('\\clef "' + CLEF_MAP[event.clef] + '"');
+    }
+    // Key signature
+    if (event.key) {
+        let keyStr = String(event.key.pitch);
+        if (event.key.accidental) {
+            keyStr += ACCIDENTAL_MAP[event.key.accidental] || '';
+        }
+        keyStr += ' \\' + event.key.mode;
+        parts.push('\\key ' + keyStr);
+    }
+    // Time signature
+    if (event.time) {
+        parts.push('\\time ' + event.time.numerator + '/' + event.time.denominator);
+    }
+    // Partial (pickup measure duration check)
+    if (event.partial) {
+        parts.push('\\partial ' + event.partial.division + '.'.repeat(event.partial.dots || 0));
+    }
+    // Ottava
+    if (event.ottava !== undefined) {
+        if (event.ottava === 0) {
+            parts.push('\\ottava #0');
+        }
+        else {
+            parts.push('\\ottava #' + event.ottava);
+        }
+    }
+    // Stem direction
+    if (event.stemDirection) {
+        if (event.stemDirection === StemDirection.up) {
+            parts.push('\\stemUp');
+        }
+        else if (event.stemDirection === StemDirection.down) {
+            parts.push('\\stemDown');
+        }
+        else if (event.stemDirection === StemDirection.auto) {
+            parts.push('\\stemNeutral');
+        }
+    }
+    // Tempo
+    if (event.tempo) {
+        parts.push(serializeTempo(event.tempo));
+    }
+    return parts.join(' ');
+};
+// Serialize tempo
+const serializeTempo = (tempo) => {
+    const parts = ['\\tempo'];
+    if (tempo.text) {
+        parts.push('"' + tempo.text + '"');
+    }
+    if (tempo.beat && tempo.bpm) {
+        parts.push(tempo.beat.division + '=' + tempo.bpm);
+    }
+    return parts.join(' ');
+};
+// Serialize a tuplet event with pitch environment tracking
+const serializeTupletEvent = (event, env) => {
+    const parts = [];
+    let currentEnv = env;
+    // \tuplet denominator/numerator { ... } for tuplet type, \times numerator/denominator for times type
+    const keyword = event.type === 'times'
+        ? '\\times ' + event.ratio.numerator + '/' + event.ratio.denominator
+        : '\\tuplet ' + event.ratio.denominator + '/' + event.ratio.numerator;
+    parts.push(keyword + ' {');
+    let prevDuration;
+    for (const e of event.events) {
+        if (e.type === 'note') {
+            const { str, newEnv } = serializeNoteEvent(e, currentEnv, prevDuration);
+            parts.push(' ' + str);
+            currentEnv = newEnv;
+            prevDuration = e.duration;
+        }
+        else if (e.type === 'rest') {
+            const { str, newEnv } = serializeRestEvent(e, currentEnv, prevDuration);
+            parts.push(' ' + str);
+            currentEnv = newEnv;
+            prevDuration = e.duration;
+        }
+        else if (e.type === 'context') {
+            const ctx = e;
+            if (ctx.staff != null) {
+                parts.push(' \\staff "' + ctx.staff + '"');
+            }
+            else if (ctx.stemDirection != null) {
+                if (ctx.stemDirection === StemDirection.up)
+                    parts.push(' \\stemUp');
+                else if (ctx.stemDirection === StemDirection.down)
+                    parts.push(' \\stemDown');
+                else if (ctx.stemDirection === StemDirection.auto)
+                    parts.push(' \\stemNeutral');
+            }
+        }
+    }
+    parts.push(' }');
+    return { str: parts.join(''), newEnv: currentEnv };
+};
+// Serialize a tremolo event with pitch environment tracking
+const serializeTremoloEvent = (event, env) => {
+    const parts = [];
+    let currentEnv = env;
+    // \repeat tremolo count { noteA noteB }
+    parts.push('\\repeat tremolo ' + event.count + ' {');
+    // First pitch/chord
+    if (event.pitchA.length === 1) {
+        const { str, newEnv } = serializePitchRelative(event.pitchA[0], currentEnv);
+        parts.push(' ' + str + event.division);
+        currentEnv = newEnv;
+    }
+    else {
+        const pitchStrs = [];
+        const { str: firstStr, newEnv: firstEnv } = serializePitchRelative(event.pitchA[0], currentEnv);
+        pitchStrs.push(firstStr);
+        currentEnv = firstEnv;
+        let chordEnv = { ...currentEnv };
+        for (let i = 1; i < event.pitchA.length; i++) {
+            const { str, newEnv } = serializePitchRelative(event.pitchA[i], chordEnv);
+            pitchStrs.push(str);
+            chordEnv = newEnv;
+        }
+        parts.push(' <' + pitchStrs.join(' ') + '>' + event.division);
+    }
+    // Second pitch/chord
+    if (event.pitchB.length === 1) {
+        const { str, newEnv } = serializePitchRelative(event.pitchB[0], currentEnv);
+        parts.push(' ' + str + event.division);
+        currentEnv = newEnv;
+    }
+    else {
+        const pitchStrs = [];
+        const { str: firstStr, newEnv: firstEnv } = serializePitchRelative(event.pitchB[0], currentEnv);
+        pitchStrs.push(firstStr);
+        currentEnv = firstEnv;
+        let chordEnv = { ...currentEnv };
+        for (let i = 1; i < event.pitchB.length; i++) {
+            const { str, newEnv } = serializePitchRelative(event.pitchB[i], chordEnv);
+            pitchStrs.push(str);
+            chordEnv = newEnv;
+        }
+        parts.push(' <' + pitchStrs.join(' ') + '>' + event.division);
+    }
+    parts.push(' }');
+    return { str: parts.join(''), newEnv: currentEnv };
+};
+// Serialize a barline event
+const serializeBarlineEvent = (event) => {
+    // Only output non-default barlines
+    if (event.style && event.style !== '|') {
+        return '\\bar "' + event.style + '"';
+    }
+    return '';
+};
+// Serialize a single event with pitch environment tracking
+const serializeEvent = (event, env, prevDuration) => {
+    switch (event.type) {
+        case 'note':
+            return serializeNoteEvent(event, env, prevDuration);
+        case 'rest':
+            return serializeRestEvent(event, env, prevDuration);
+        case 'context':
+            return { str: serializeContextChange(event), newEnv: env };
+        case 'tuplet':
+        case 'times':
+            return serializeTupletEvent(event, env);
+        case 'tremolo':
+            return serializeTremoloEvent(event, env);
+        case 'barline':
+            return { str: serializeBarlineEvent(event), newEnv: env };
+        default:
+            return { str: '', newEnv: env };
+    }
+};
+// Find first clef in voice events
+const findVoiceClef = (voice) => {
+    let activeStaff = voice.staff;
+    for (const event of voice.events) {
+        if (event.type === 'context') {
+            const ctx = event;
+            if (ctx.staff)
+                activeStaff = ctx.staff;
+            if (ctx.clef && activeStaff === voice.staff) {
+                return ctx.clef;
+            }
+        }
+    }
+    return undefined;
+};
+// Serialize a voice with pitch environment tracking
+// Takes currentStaff (what parser thinks staff is) and returns { str, newStaff }
+// If isGrandStaff is true, always output \staff command for clarity
+// measureContext provides key/time for first voice
+// allStaffClefs is the clef map for all staves (tracked across measures)
+// emittedClefs tracks which clefs have already been output (avoids duplicates)
+const serializeVoice = (voice, currentStaff, isGrandStaff = false, measureContext, isFirstVoice = false, allStaffClefs, emittedClefs) => {
+    const parts = [];
+    let prevDuration;
+    // Each voice starts fresh from middle C (step=0, octave=0)
+    let pitchEnv = { step: 0, octave: 0 };
+    // Scan leading context-staff events (before the first musical event or clef/ottava)
+    // to compute the effective initial staff. Multiple consecutive staff switches
+    // before any music collapse to the last one (earlier ones are no-ops).
+    // leadStaffScanEnd is the index of the first event that ends this scan —
+    // context{staff} events before this index are skipped in the main loop.
+    const MUSICAL_TYPES = new Set(['note', 'rest', 'tuplet', 'times', 'tremolo']);
+    let effectiveInitialStaff = voice.staff;
+    let leadStaffScanEnd = 0;
+    for (let i = 0; i < voice.events.length; i++) {
+        const e = voice.events[i];
+        if (e.type === 'pitchReset') {
+            leadStaffScanEnd = i + 1;
+            continue;
+        }
+        if (e.type === 'context') {
+            const ctx = e;
+            if (ctx.staff != null) {
+                effectiveInitialStaff = ctx.staff;
+                if (!ctx.clef && !ctx.ottava) {
+                    // Pure staff-only event — absorb
+                    leadStaffScanEnd = i + 1;
+                    continue;
+                }
+                // Compound (staff + clef/ottava) — update effectiveInitialStaff but stop scan
+                break;
+            }
+            if (ctx.clef || ctx.ottava)
+                break; // musical context — stop scan
+            leadStaffScanEnd = i + 1; // time/key/stemDir — continue scan
+            continue;
+        }
+        if (MUSICAL_TYPES.has(e.type))
+            break;
+    }
+    // Output staff command if voice staff differs from current parser staff,
+    // or always output if it's a grand staff score for clarity.
+    // Use effectiveInitialStaff so carry-over replaces the default emission.
+    if (isGrandStaff || effectiveInitialStaff !== currentStaff) {
+        parts.push('\\staff "' + effectiveInitialStaff + '"');
+    }
+    // Output key/time signatures after \staff (for first voice only)
+    if (measureContext && isFirstVoice) {
+        if (measureContext.key) {
+            let keyStr = String(measureContext.key.pitch);
+            if (measureContext.key.accidental) {
+                keyStr += ACCIDENTAL_MAP[measureContext.key.accidental] || '';
+            }
+            keyStr += ' \\' + measureContext.key.mode;
+            parts.push('\\key ' + keyStr);
+        }
+        if (measureContext.time) {
+            const { numerator, denominator, symbol } = measureContext.time;
+            // Output \numericTimeSignature before 4/4 or 2/2 if no symbol is set
+            // (meaning numeric display was explicitly requested)
+            if (!symbol && ((numerator === 4 && denominator === 4) || (numerator === 2 && denominator === 2))) {
+                parts.push('\\numericTimeSignature');
+            }
+            parts.push('\\time ' + numerator + '/' + denominator);
+        }
+    }
+    // Output clef only if not yet emitted or changed for this staff
+    const voiceClef = allStaffClefs?.[voice.staff] || findVoiceClef(voice);
+    const clefAlreadyEmitted = voiceClef && emittedClefs?.[voice.staff] === voiceClef;
+    if (voiceClef && !clefAlreadyEmitted) {
+        parts.push('\\clef "' + CLEF_MAP[voiceClef] + '"');
+        if (emittedClefs)
+            emittedClefs[voice.staff] = voiceClef;
+    }
+    // Skip redundant clef context events if this staff's clef is already established
+    const clefOutputted = !!voiceClef && !!emittedClefs?.[voice.staff];
+    let activeStaff = effectiveInitialStaff;
+    let activeStemDir;
+    for (let eventIdx = 0; eventIdx < voice.events.length; eventIdx++) {
+        const event = voice.events[eventIdx];
+        // Skip leading context-staff events already absorbed into effectiveInitialStaff
+        if (eventIdx < leadStaffScanEnd && event.type === 'context' && event.staff != null) {
+            continue;
+        }
+        if (event.type === 'context') {
+            const ctx = event;
+            // Cross-staff context: update activeStaff and emit \staff directive
+            if (ctx.staff && ctx.staff !== activeStaff) {
+                activeStaff = ctx.staff;
+                parts.push('\\staff "' + activeStaff + '"');
+                // Emit target staff clef if the event carries one or allStaffClefs knows it
+                const ctxClef = ctx.clef || allStaffClefs?.[activeStaff];
+                if (ctxClef && emittedClefs?.[activeStaff] !== ctxClef) {
+                    parts.push('\\clef "' + CLEF_MAP[ctxClef] + '"');
+                    if (emittedClefs)
+                        emittedClefs[activeStaff] = ctxClef;
+                }
+                continue;
+            }
+            if (ctx.staff && !ctx.clef && !ctx.ottava)
+                continue; // same staff, pure no-op
+            if (ctx.staff) { /* same staff but has clef/ottava — fall through to emit them */ }
+            // Skip clef-only context events if clef already established for this staff
+            if (clefOutputted && ctx.clef && !ctx.key && !ctx.time && !ctx.ottava && !ctx.stemDirection && !ctx.tempo) {
+                continue;
+            }
+        }
+        if (event.type === 'note') {
+            const noteEvt = event;
+            // Cross-staff via explicit note.staff (lilylet native cross-staff)
+            const effectiveStaff = noteEvt.staff || activeStaff;
+            if (effectiveStaff !== activeStaff) {
+                activeStaff = effectiveStaff;
+                parts.push('\\staff "' + activeStaff + '"');
+                // Emit the target staff's clef if it differs from what was last emitted for this staff
+                const targetClef = allStaffClefs?.[activeStaff];
+                if (targetClef && emittedClefs?.[activeStaff] !== targetClef) {
+                    parts.push('\\clef "' + CLEF_MAP[targetClef] + '"');
+                    if (emittedClefs)
+                        emittedClefs[activeStaff] = targetClef;
+                }
+            }
+            // Stem direction: emit \stemUp/\stemDown/\stemNeutral on change
+            const stemDir = noteEvt.stemDirection;
+            if (stemDir !== activeStemDir) {
+                if (stemDir === StemDirection.up) {
+                    parts.push('\\stemUp');
+                }
+                else if (stemDir === StemDirection.down) {
+                    parts.push('\\stemDown');
+                }
+                else if (activeStemDir) {
+                    // Was set, now undefined → reset to neutral
+                    parts.push('\\stemNeutral');
+                }
+                activeStemDir = stemDir;
+            }
+        }
+        const { str: eventStr, newEnv } = serializeEvent(event, pitchEnv, prevDuration);
+        pitchEnv = newEnv;
+        if (eventStr) {
+            parts.push(eventStr);
+        }
+        // Track duration for note/rest events
+        if (event.type === 'note') {
+            prevDuration = event.duration;
+        }
+        else if (event.type === 'rest') {
+            prevDuration = event.duration;
+        }
+        else if (event.type === 'tuplet' || event.type === 'times') {
+            // After a tuplet/times block the LilyPond parser's "current duration" is the
+            // last note duration inside the tuplet, not the duration before the tuplet.
+            // Reset prevDuration so the first note after the block always emits its
+            // duration explicitly, avoiding wrong inheritance from inside the tuplet.
+            prevDuration = undefined;
+        }
+        else if (event.type === 'context' && event.clef && emittedClefs) {
+            const ctx = event;
+            emittedClefs[ctx.staff || activeStaff] = ctx.clef;
+        }
+    }
+    return { str: parts.join(' '), newStaff: voice.staff };
+};
+// Serialize a part, tracking staff state across voices
+// measureContext is passed to all voices (for clef), but key/time only to first voice
+const serializePart = (part, currentStaff, isGrandStaff = false, measureContext, isFirstPart = false, clefsByStaff, emittedClefs) => {
+    if (part.voices.length === 0) {
+        return { str: '', newStaff: currentStaff };
+    }
+    const voiceStrs = [];
+    let staff = currentStaff;
+    for (let i = 0; i < part.voices.length; i++) {
+        const voice = part.voices[i];
+        // Pass measureContext to all voices, isFirstVoice for key/time
+        const isFirstVoice = isFirstPart && i === 0;
+        const { str, newStaff } = serializeVoice(voice, staff, isGrandStaff, measureContext, isFirstVoice, clefsByStaff, emittedClefs);
+        voiceStrs.push(str);
+        staff = newStaff;
+    }
+    // Multiple voices: separated by \\ with newline
+    return { str: voiceStrs.join(' \\\\\n'), newStaff: staff };
+};
+// Serialize a measure, tracking staff state across parts
+// Always output key/time at start of each measure
+const serializeMeasure = (measure, _isFirst, currentStaff, isGrandStaff = false, currentKey, currentTime, staffClefs, emittedClefs) => {
+    const parts = [];
+    // Build measure context for all voices (key/time)
+    // Key and time are written to first voice, clef to all voices based on staff
+    // Use passed currentKey/currentTime which tracks across all measures
+    const measureContext = {
+        key: currentKey,
+        time: currentTime,
+    };
+    // Pass staffClefs to parts for per-voice clef lookup
+    const clefsByStaff = staffClefs || {};
+    // Parts
+    let staff = currentStaff;
+    if (measure.parts.length === 1) {
+        const { str: partStr, newStaff } = serializePart(measure.parts[0], staff, isGrandStaff, measureContext, true, clefsByStaff, emittedClefs);
+        if (partStr) {
+            parts.push(partStr);
+        }
+        staff = newStaff;
+    }
+    else if (measure.parts.length > 1) {
+        // Multiple parts: separated by \\\ with newline
+        const partStrs = [];
+        for (let i = 0; i < measure.parts.length; i++) {
+            const part = measure.parts[i];
+            // Pass measureContext to all parts, isFirstPart to first part only
+            const { str, newStaff } = serializePart(part, staff, isGrandStaff, measureContext, i === 0, clefsByStaff, emittedClefs);
+            if (str) {
+                partStrs.push(str);
+            }
+            staff = newStaff;
+        }
+        parts.push(partStrs.join(' \\\\\\\n'));
+    }
+    return { str: parts.join(' '), newStaff: staff };
+};
+// Escape string for serialization (quotes and backslashes)
+const escapeString = (str) => {
+    return str.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+};
+// Serialize metadata
+const serializeMetadata = (metadata) => {
+    const lines = [];
+    if (metadata.title) {
+        lines.push('[title "' + escapeString(metadata.title) + '"]');
+    }
+    if (metadata.subtitle) {
+        lines.push('[subtitle "' + escapeString(metadata.subtitle) + '"]');
+    }
+    if (metadata.composer) {
+        lines.push('[composer "' + escapeString(metadata.composer) + '"]');
+    }
+    if (metadata.arranger) {
+        lines.push('[arranger "' + escapeString(metadata.arranger) + '"]');
+    }
+    if (metadata.lyricist) {
+        lines.push('[lyricist "' + escapeString(metadata.lyricist) + '"]');
+    }
+    if (metadata.autoBeam) {
+        lines.push('[auto-beam "' + escapeString(metadata.autoBeam) + '"]');
+    }
+    return lines.join('\n');
+};
+/**
+ * Serialize a LilyletDoc to Lilylet (.lyl) string format
+ */
+export const serializeLilyletDoc = (doc) => {
+    const parts = [];
+    // Metadata
+    if (doc.metadata) {
+        const metaStr = serializeMetadata(doc.metadata);
+        if (metaStr) {
+            parts.push(metaStr);
+            parts.push('');
+        }
+    }
+    // Detect grand staff: check if any voice has staff > 1
+    const isGrandStaff = doc.measures.some(m => m.parts.some(p => p.voices.some(v => v.staff > 1)));
+    // Measures with bar lines, measure numbers, and double newlines
+    // Track staff state across measures (parser remembers staff across bar lines)
+    // Track key/time/clef across measures to output in every measure
+    const measureStrs = [];
+    let currentStaff = 1; // Parser starts at staff 1
+    let currentKey;
+    let currentTime;
+    const staffClefs = {}; // Track clef per staff
+    const emittedClefs = {}; // Track which clefs have been output
+    for (let i = 0; i < doc.measures.length; i++) {
+        const measure = doc.measures[i];
+        // Update current key/time if measure has them
+        if (measure.key) {
+            currentKey = measure.key;
+        }
+        if (measure.timeSig) {
+            currentTime = measure.timeSig;
+        }
+        // Collect clefs from this measure's voices
+        for (const part of measure.parts) {
+            for (const voice of part.voices) {
+                let clefActiveStaff = voice.staff;
+                for (const event of voice.events) {
+                    if (event.type === 'context') {
+                        const ctx = event;
+                        if (ctx.staff) {
+                            clefActiveStaff = ctx.staff;
+                        }
+                        if (ctx.clef) {
+                            staffClefs[clefActiveStaff] = ctx.clef;
+                        }
+                    }
+                }
+            }
+        }
+        const { str: measureStr, newStaff } = serializeMeasure(measure, i === 0, currentStaff, isGrandStaff, currentKey, currentTime, staffClefs, emittedClefs);
+        // Always include measure, even if empty (use space rest for empty measures)
+        measureStrs.push(measureStr || 's1');
+        currentStaff = newStaff;
+    }
+    // Join measures with bar, measure number comment, and double newline
+    const measuresOutput = measureStrs
+        .map((m, i) => m + ' | %' + (i + 1))
+        .join('\n\n');
+    parts.push(measuresOutput);
+    return parts.join('\n');
+};