@k-l-lambda/lilylet 0.1.74 → 0.1.76

package/lib/lilylet/meiEncoder.js

@@ -1,6 +1,7 @@
 import { Clef, Accidental, OrnamentType, StemDirection, HairpinType, PedalType, } from "./types.js";
 import { parseStaffLayout, StaffGroupType } from "./staffLayout.js";
 import { gmProgramOf } from "./gmInstruments.js";
+import { parseMeasureLayout, expandMeasureLayout, decomposeToSegments } from "./measureLayout.js";
 // MEI key signatures: positive = sharps, negative = flats
 const KEY_SIGS = {
     0: "0",
@@ -641,6 +642,7 @@ const tupletEventToMEI = (event, indent, layerStaff, keyFifths = 0, currentStaff
     const effectiveStaff = currentStaff ?? layerStaff;
     // Collect control event info from notes inside tuplet
     let firstNoteId = null;
+    let lastNoteId = null; // last note/rest id — anchors an ottava span end
     const slurStarts = [];
     const slurEnds = [];
     const dynamics = [];
@@ -675,6 +677,7 @@ const tupletEventToMEI = (event, indent, layerStaff, keyFifths = 0, currentStaff
             xml += result.xml;
             if (!firstNoteId)
                 firstNoteId = result.elementId;
+            lastNoteId = result.elementId;
             // Collect slur info
             if (result.slurStart)
                 slurStarts.push(result.elementId);
@@ -714,6 +717,7 @@ const tupletEventToMEI = (event, indent, layerStaff, keyFifths = 0, currentStaff
             const restIndent = beamOpen ? baseIndent + '    ' : baseIndent;
             const restResult = restEventToMEI(e, restIndent, keyFifths, ottavaShift, measureAccidentals);
             xml += restResult.xml;
+            lastNoteId = restResult.elementId;
             if (restResult.fermata)
                 fermatas.push({ startid: restResult.elementId, shape: restResult.fermata === 'short' ? 'angular' : undefined });
         }
@@ -736,7 +740,7 @@ const tupletEventToMEI = (event, indent, layerStaff, keyFifths = 0, currentStaff
         xml += `${baseIndent}</beam>\n`;
     }
     xml += `${indent}</tuplet>\n`;
-    return { xml, firstNoteId, slurStarts, slurEnds, dynamics, fermatas, trills, mordents, turns, arpeggios, pedals, fingerings, markups, endingClef };
+    return { xml, firstNoteId, lastNoteId, slurStarts, slurEnds, dynamics, fermatas, trills, mordents, turns, arpeggios, pedals, fingerings, markups, endingClef };
 };
 // Convert TremoloEvent to MEI (fingered tremolo - alternating between two notes)
 const tremoloEventToMEI = (event, indent, keyFifths = 0, ottavaShift = 0, measureAccidentals) => {
@@ -866,6 +870,43 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
     let currentOttavaShift = initialOctave?.shift || 0; // Track current ottava shift for pitch encoding
     let lastNoteId = null; // Track last note id for ending ottava spans
     let ottavaExplicitlyClosed = false; // Track if ottava was explicitly closed by \ottava #0
+    // ── Ottava span anchoring (shared by note / rest / tuplet cases) ──
+    // Originally the open/extend/close logic lived ONLY in `case 'note'`, so an
+    // ottava span running over a tuplet run (ubiquitous in etudes) or over rests
+    // was never opened — the whole span vanished (No.26 10→0, No.20 7→0). These
+    // helpers let any event type anchor a span. Mirror the note-case ordering:
+    // the caller updates lastNoteId to the event's first emitted id, THEN calls
+    // these.
+    // Apply a pending ottava's pitch shift before the event's notes are encoded.
+    const applyPendingOttavaShift = () => {
+        if (pendingOttava !== null && pendingOttava !== 0)
+            currentOttavaShift = pendingOttava;
+    };
+    // Extend a carried (endToken) span's end to this event's last emitted id.
+    const extendOttavaEnd = (lastId) => {
+        if (currentOctave?.endToken)
+            octaveEndReplacements[currentOctave.endToken] = lastId;
+    };
+    // Open the pending ottava span on `anchorId` (the event's FIRST emitted id),
+    // closing any open span of a different value first; or resolve a continued span.
+    const applyOttavaAnchor = (anchorId) => {
+        if (pendingOttava !== null && pendingOttava !== 0) {
+            const dis = Math.abs(pendingOttava) === 2 ? 15 : 8;
+            const disPlace = pendingOttava > 0 ? 'above' : 'below';
+            if (currentOctave && (currentOctave.dis !== dis || currentOctave.disPlace !== disPlace)) {
+                octaves.push({ dis: currentOctave.dis, disPlace: currentOctave.disPlace, startId: currentOctave.startId, endId: anchorId });
+                currentOctave = null;
+            }
+            if (!currentOctave)
+                currentOctave = { dis, disPlace, startId: anchorId };
+            pendingOttava = null;
+        }
+        else if (currentOctave?.continued) {
+            if (!currentOctave.endToken)
+                currentOctave.startId = anchorId;
+            currentOctave.continued = false;
+        }
+    };
     // Track slur spans - slurs must be encoded as control events in MEI.
     // A single slot can't hold the overlapping/concurrent slurs that piano writing
     // produces (measured up to 3 open at once per voice); a new start while one was
@@ -957,9 +998,7 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
                 // Check if this note should have tie="t" (matches pending tie)
                 const tieEnd = pendingTiePitches.length > 0 && pitchesMatch(pendingTiePitches, noteEvent.pitches);
                 // If there's a pending ottava, apply it BEFORE encoding the note
-                if (pendingOttava !== null && pendingOttava !== 0) {
-                    currentOttavaShift = pendingOttava; // Apply the shift for this note
-                }
+                applyPendingOttavaShift();
                 // For cross-staff notation: set note's staff to currentStaff if different from voice.staff
                 const effectiveNoteEvent = currentStaff !== voice.staff
                     ? { ...noteEvent, staff: currentStaff }
@@ -967,41 +1006,13 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
                 const result = noteEventToMEI(effectiveNoteEvent, currentIndent, voice.staff, tieEnd, currentStemDirection, keyFifths, currentOttavaShift, measureAccidentals);
                 xml += result.xml;
                 lastNoteId = result.elementId;
-                if (currentOctave?.endToken) {
-                    octaveEndReplacements[currentOctave.endToken] = result.elementId;
-                }
+                extendOttavaEnd(result.elementId);
                 // Flush any pending markups onto this note
                 flushPendingMarkups(result.elementId);
                 // Flush any pending leading dynamics onto this note
                 flushPendingDynamics(result.elementId);
                 // If there's a pending ottava, start the span on this note
-                if (pendingOttava !== null && pendingOttava !== 0) {
-                    const dis = Math.abs(pendingOttava) === 2 ? 15 : 8;
-                    const disPlace = pendingOttava > 0 ? 'above' : 'below';
-                    // Close existing span first if it has a different value
-                    if (currentOctave && (currentOctave.dis !== dis || currentOctave.disPlace !== disPlace)) {
-                        if (lastNoteId) {
-                            octaves.push({
-                                dis: currentOctave.dis,
-                                disPlace: currentOctave.disPlace,
-                                startId: currentOctave.startId,
-                                endId: lastNoteId,
-                            });
-                        }
-                        currentOctave = null;
-                    }
-                    // Start new span if we don't already have one with the same value
-                    if (!currentOctave) {
-                        currentOctave = { dis, disPlace, startId: result.elementId };
-                    }
-                    pendingOttava = null;
-                }
-                else if (currentOctave?.continued) {
-                    if (!currentOctave.endToken) {
-                        currentOctave.startId = result.elementId;
-                    }
-                    currentOctave.continued = false;
-                }
+                applyOttavaAnchor(result.elementId);
                 // Update pending tie pitches
                 if (result.hasTieStart) {
                     pendingTiePitches = result.pitches;
@@ -1101,23 +1112,39 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
             case 'rest': {
                 // For cross-staff notation: pass staff number if different from voice's home staff
                 const restCrossStaff = currentStaff !== (voice.staff || 1) ? currentStaff : undefined;
+                // A pending ottava shift applies to a rest's gestural octave too.
+                applyPendingOttavaShift();
                 const restResult = restEventToMEI(event, currentIndent, keyFifths, currentOttavaShift, measureAccidentals, restCrossStaff);
                 xml += restResult.xml;
+                lastNoteId = restResult.elementId;
+                // An ottava span may open on, run through, or close at a rest (e.g. a
+                // span that starts just before LH rests). Anchor it like a note.
+                extendOttavaEnd(restResult.elementId);
+                applyOttavaAnchor(restResult.elementId);
                 // Fermata over a rest (held silence) — emit as a control event on the rest.
                 if (restResult.fermata)
                     fermatas.push({ startid: restResult.elementId, shape: restResult.fermata === 'short' ? 'angular' : undefined });
                 // A leading dynamic/markup attaches to the next event, which may be this rest
                 flushPendingMarkups(restResult.elementId);
                 flushPendingDynamics(restResult.elementId);
-                lastNoteId = restResult.elementId;
                 break;
             }
             case 'tuplet':
             case 'times': {
                 // Tuplet can be nested inside beam in MEI: <beam><tuplet>...</tuplet></beam>
                 // Pass beamElementOpen to tuplet so it knows not to create its own beam
+                // A pending ottava shift applies to the tuplet's notes' written octave.
+                applyPendingOttavaShift();
                 const tupletResult = tupletEventToMEI(event, currentIndent, voice.staff, keyFifths, currentStaff, currentOttavaShift, beamElementOpen, measureAccidentals, currentClef);
                 xml += tupletResult.xml;
+                // An ottava span can open on, run through, or close at a tuplet (common
+                // in etudes where the 8va covers a whole tuplet run). Anchor the span on
+                // the tuplet's FIRST note and let its LAST note close/extend it — without
+                // this the entire span was dropped (start/close lived only in case 'note').
+                if (tupletResult.firstNoteId)
+                    applyOttavaAnchor(tupletResult.firstNoteId);
+                if (tupletResult.lastNoteId)
+                    extendOttavaEnd(tupletResult.lastNoteId);
                 // Propagate clef change from inside the tuplet to the parent tracker
                 if (tupletResult.endingClef) {
                     currentClef = tupletResult.endingClef;
@@ -1126,7 +1153,7 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
                 if (tupletResult.firstNoteId) {
                     flushPendingMarkups(tupletResult.firstNoteId);
                     flushPendingDynamics(tupletResult.firstNoteId);
-                    lastNoteId = tupletResult.firstNoteId;
+                    lastNoteId = tupletResult.lastNoteId ?? tupletResult.firstNoteId;
                 }
                 // Process slur ends first (to close open slurs, LIFO), then starts.
                 for (const endId of tupletResult.slurEnds) {
@@ -1185,8 +1212,22 @@ const encodeLayer = (voice, layerN, indent, initialTiePitches = [], keyFifths =
                             currentOctave = null;
                             ottavaExplicitlyClosed = true; // Mark that we explicitly closed the span
                         }
-                        // Note: if no lastNoteId (e.g., at measure start), keep currentOctave alive
-                        // It may be continued by a subsequent ottava command with the same value
+                        else if (currentOctave && currentOctave.emitted) {
+                            // Stop landed at measure START (no note yet in this layer) but the
+                            // span was carried+emitted in a PREVIOUS measure: it genuinely ends
+                            // here. Its deferred endToken was already resolved to the correct
+                            // last note by extendOttavaEnd as the span ran through prior measures
+                            // (or by the staff-level carry's endFallbackId), so DON'T rewrite it
+                            // here — just clear the slot and mark closed, so a later same-value
+                            // ottava opens a NEW span instead of folding into this one.
+                            // Without this, sequential cross-measure spans collapse into one
+                            // (No.57: 18 spans → 8).
+                            currentOctave = null;
+                            ottavaExplicitlyClosed = true;
+                        }
+                        // Note: if no lastNoteId and not yet emitted (e.g., open+close at
+                        // measure start with no notes), keep currentOctave alive — it may be
+                        // continued by a subsequent ottava command with the same value.
                         currentOttavaShift = 0; // Reset the shift (will be restored if continued)
                     }
                     else {
@@ -1525,8 +1566,10 @@ const BARLINE_TO_MEI = {
 };
 // Encode a measure
 // encodeMeasure accepts mutable tieState, slurState, hairpinState, ottavaState and clefState that persist across measures
-const encodeMeasure = (measure, measureN, indent, totalStaves, tieState, slurState, hairpinState, ottavaState, keyFifths = 0, partInfos = [], clefState = {}, octaveEndReplacements = {}) => {
+const encodeMeasure = (measure, measureN, indent, totalStaves, tieState, slurState, hairpinState, ottavaState, keyFifths = 0, partInfos = [], clefState = {}, octaveEndReplacements = {}, measureIds) => {
     const measureId = generateId("measure");
+    if (measureIds)
+        measureIds.push(measureId);
     let staffContent = ''; // Build staff content first, then add measure tag with barline
     const allHairpins = [];
     const allPedals = [];
@@ -2246,6 +2289,75 @@ const encode = (doc, options = {}) => {
     mei += `${indent}${indent}${indent}${indent}<score xml:id="${generateId("score")}">\n`;
     mei += encodeScoreDef(keySig, currentTimeNum, currentTimeDen, partInfos, `${indent}${indent}${indent}${indent}${indent}`, currentMeterSymbol, doc.metadata?.staves, doc.metadata?.instruments);
     mei += `${indent}${indent}${indent}${indent}${indent}<section xml:id="${generateId("section")}">\n`;
+    // Splice point for an <expansion> element (must be the FIRST child of
+    // <section>, but its plist needs the measure ids collected during the loop
+    // below — so remember where to insert it and build it afterwards).
+    const expansionInsertPos = mei.length;
+    const measureIds = [];
+    // Volta playback + house brackets. A flat measure-level <expansion> conflicts
+    // with <ending> wrappers in verovio (it then drops the volta measures). Verovio
+    // instead wants nested <section>/<ending> groups with a SECTION-LEVEL expansion
+    // whose plist references those segment ids. So when the layout decomposes into
+    // volta segments, emit that structure; otherwise keep the simpler flat path.
+    // See [[volta-rendering-gaps]] / [[lilylet-measure-layout]].
+    // Helper to check if a measure has any musical content
+    const measureHasContent = (measure) => {
+        for (const part of measure.parts) {
+            for (const voice of part.voices) {
+                for (const event of voice.events) {
+                    // Check for actual musical content (not just context changes or pitch resets)
+                    if (event.type === 'note' || event.type === 'rest' ||
+                        event.type === 'tuplet' || event.type === 'times' || event.type === 'tremolo') {
+                        return true;
+                    }
+                }
+            }
+        }
+        return false;
+    };
+    // Filter out trailing empty measures (done before segment setup so the segment
+    // guard below knows the true emitted measure count).
+    let measures = doc.measures;
+    while (measures.length > 0 && !measureHasContent(measures[measures.length - 1])) {
+        measures = measures.slice(0, -1);
+    }
+    let segDecomp = null;
+    const segOpenAt = new Map(); // measure index → opening tag for its segment
+    const segCloseAt = new Map(); // measure index → closing tag after it
+    const segIdById = new Map(); // layout segment id → emitted xml:id
+    if (doc.metadata?.measureLayout) {
+        try {
+            segDecomp = decomposeToSegments(parseMeasureLayout(doc.metadata.measureLayout));
+        }
+        catch {
+            segDecomp = null;
+        }
+    }
+    // A layout that references a measure beyond the emitted range (e.g. a volta
+    // alternate whose bar was a trailing empty measure that got trimmed) cannot be
+    // emitted as nested sections without a dangling <ending>/<section> id or an
+    // unbalanced wrapper. Drop to the flat measure-level expansion path, which
+    // already warns-and-skips out-of-range refs.
+    if (segDecomp && segDecomp.segments.some(seg => seg.measures.some(m => m > measures.length))) {
+        segDecomp = null;
+    }
+    if (segDecomp) {
+        const segIndent = `${indent}${indent}${indent}${indent}${indent}${indent}`;
+        for (const seg of segDecomp.segments) {
+            const xmlId = generateId(seg.kind === "ending" ? "ending" : "section");
+            segIdById.set(seg.id, xmlId);
+            const lo = seg.measures[0];
+            const hi = seg.measures[seg.measures.length - 1];
+            if (seg.kind === "ending") {
+                const lendsym = seg.endingNumber === 1 ? ' lendsym="angledown"' : '';
+                segOpenAt.set(lo, `${segIndent}<ending xml:id="${xmlId}" n="${seg.endingNumber}"${lendsym}>\n`);
+            }
+            else {
+                segOpenAt.set(lo, `${segIndent}<section xml:id="${xmlId}">\n`);
+            }
+            segCloseAt.set(hi, `${segIndent}</${seg.kind === "ending" ? "ending" : "section"}>\n`);
+        }
+    }
     // Track tie state across measures for cross-measure ties
     const tieState = {};
     // Track slur state across measures for cross-measure slurs
@@ -2271,26 +2383,6 @@ const encode = (doc, options = {}) => {
             transState[globalStaff] = `${t.diat},${t.semi}`;
         }
     }
-    // Helper to check if a measure has any musical content
-    const measureHasContent = (measure) => {
-        for (const part of measure.parts) {
-            for (const voice of part.voices) {
-                for (const event of voice.events) {
-                    // Check for actual musical content (not just context changes or pitch resets)
-                    if (event.type === 'note' || event.type === 'rest' ||
-                        event.type === 'tuplet' || event.type === 'times' || event.type === 'tremolo') {
-                        return true;
-                    }
-                }
-            }
-        }
-        return false;
-    };
-    // Filter out trailing empty measures
-    let measures = doc.measures;
-    while (measures.length > 0 && !measureHasContent(measures[measures.length - 1])) {
-        measures = measures.slice(0, -1);
-    }
     // Encode measures
     measures.forEach((measure, mi) => {
         // Check for key signature change and output scoreDef if needed
@@ -2352,8 +2444,57 @@ const encode = (doc, options = {}) => {
                 mei += `${sd}</scoreDef>\n`;
             }
         }
-        mei += encodeMeasure(measure, mi + 1, `${indent}${indent}${indent}${indent}${indent}${indent}`, totalStaves, tieState, slurState, hairpinState, ottavaState, currentKey, partInfos, clefState, octaveEndReplacements);
+        const mIndex = mi + 1;
+        const mIndent = `${indent}${indent}${indent}${indent}${indent}${indent}`;
+        // When the layout decomposes into volta segments, wrap each measure run in
+        // its <section>/<ending> container (opened/closed by measure index).
+        const openTag = segOpenAt.get(mIndex);
+        if (openTag)
+            mei += openTag;
+        const measureIndent = segDecomp ? `${mIndent}${indent}` : mIndent;
+        mei += encodeMeasure(measure, mIndex, measureIndent, totalStaves, tieState, slurState, hairpinState, ottavaState, currentKey, partInfos, clefState, octaveEndReplacements, measureIds);
+        const closeTag = segCloseAt.get(mIndex);
+        if (closeTag)
+            mei += closeTag;
     });
+    // Emit an <expansion> describing playback order from the measure-layout
+    // directive ([measures "..."]). Verovio consumes its plist to unfold repeats
+    // for MIDI/time-map output. Inserted as the first child of <section>.
+    //   - voltas present (segDecomp): plist references the SECTION/ENDING segment
+    //     ids in performed order (a body segment id repeats per pass). This is the
+    //     only form verovio plays correctly alongside <ending> house brackets.
+    //   - otherwise: the simpler flat measure-level plist (one ref per played bar).
+    if (segDecomp) {
+        const refs = segDecomp.order.map(segId => segIdById.get(segId)).filter((x) => x !== undefined).map(id => `#${id}`);
+        if (refs.length > 0) {
+            const expIndent = `${indent}${indent}${indent}${indent}${indent}${indent}`;
+            const expXml = `${expIndent}<expansion xml:id="${generateId("expansion")}" plist="${refs.join(" ")}" />\n`;
+            mei = mei.slice(0, expansionInsertPos) + expXml + mei.slice(expansionInsertPos);
+        }
+    }
+    else if (doc.metadata?.measureLayout) {
+        try {
+            const layout = parseMeasureLayout(doc.metadata.measureLayout);
+            const order = expandMeasureLayout(layout);
+            const refs = [];
+            for (const idx of order) {
+                const id = measureIds[idx - 1]; // 1-based index into notated measures
+                if (id === undefined) {
+                    console.warn(`[measures] index ${idx} out of range (only ${measureIds.length} measures); skipping`);
+                    continue;
+                }
+                refs.push(`#${id}`);
+            }
+            if (refs.length > 0) {
+                const expIndent = `${indent}${indent}${indent}${indent}${indent}${indent}`;
+                const expXml = `${expIndent}<expansion xml:id="${generateId("expansion")}" plist="${refs.join(" ")}" />\n`;
+                mei = mei.slice(0, expansionInsertPos) + expXml + mei.slice(expansionInsertPos);
+            }
+        }
+        catch (err) {
+            console.warn(`[measures] failed to parse "${doc.metadata.measureLayout}": ${err.message}`);
+        }
+    }
     mei += `${indent}${indent}${indent}${indent}${indent}</section>\n`;
     mei += `${indent}${indent}${indent}${indent}</score>\n`;
     mei += `${indent}${indent}${indent}</mdiv>\n`;