@k-l-lambda/lilylet 0.1.74 → 0.1.76

package/source/lilylet/meiEncoder.ts

@@ -29,6 +29,7 @@ import {
 } from "./types";
 import { parseStaffLayout, StaffGroup, StaffGroupType } from "./staffLayout";
 import { gmProgramOf } from "./gmInstruments";
+import { parseMeasureLayout, expandMeasureLayout, decomposeToSegments } from "./measureLayout";
 
 
 // MEI key signatures: positive = sharps, negative = flats
@@ -748,6 +749,7 @@ const restEventToMEI = (event: RestEvent, indent: string, keyFifths: number = 0,
 interface TupletEventResult {
 	xml: string;
 	firstNoteId: string | null;  // ID of first note in tuplet (for attaching pending markups)
+	lastNoteId: string | null;   // ID of last note/rest in tuplet (for closing/extending ottava spans)
 	slurStarts: string[];  // Note IDs that start slurs
 	slurEnds: string[];    // Note IDs that end slurs
 	dynamics: DynamRef[];
@@ -794,6 +796,7 @@ const tupletEventToMEI = (event: TupletEvent, indent: string, layerStaff?: numbe
 
 	// Collect control event info from notes inside tuplet
 	let firstNoteId: string | null = null;
+	let lastNoteId: string | null = null;  // last note/rest id — anchors an ottava span end
 	const slurStarts: string[] = [];
 	const slurEnds: string[] = [];
 	const dynamics: DynamRef[] = [];
@@ -833,6 +836,7 @@ const tupletEventToMEI = (event: TupletEvent, indent: string, layerStaff?: numbe
 			xml += result.xml;
 
 			if (!firstNoteId) firstNoteId = result.elementId;
+			lastNoteId = result.elementId;
 
 			// Collect slur info
 			if (result.slurStart) slurStarts.push(result.elementId);
@@ -863,6 +867,7 @@ const tupletEventToMEI = (event: TupletEvent, indent: string, layerStaff?: numbe
 			const restIndent = beamOpen ? baseIndent + '    ' : baseIndent;
 			const restResult = restEventToMEI(e as RestEvent, restIndent, keyFifths, ottavaShift, measureAccidentals);
 			xml += restResult.xml;
+			lastNoteId = restResult.elementId;
 			if (restResult.fermata) fermatas.push({ startid: restResult.elementId, shape: restResult.fermata === 'short' ? 'angular' : undefined });
 		} else if (e.type === 'context') {
 			const ctx = e as ContextChange;
@@ -885,7 +890,7 @@ const tupletEventToMEI = (event: TupletEvent, indent: string, layerStaff?: numbe
 	}
 
 	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 };
 };
 
 
@@ -1143,6 +1148,39 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 	let lastNoteId: string | null = null;  // Track last note id for ending ottava spans
 	let ottavaExplicitlyClosed: boolean = 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 = (): void => {
+		if (pendingOttava !== null && pendingOttava !== 0) currentOttavaShift = pendingOttava;
+	};
+	// Extend a carried (endToken) span's end to this event's last emitted id.
+	const extendOttavaEnd = (lastId: string): void => {
+		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: string): void => {
+		if (pendingOttava !== null && pendingOttava !== 0) {
+			const dis: 8 | 15 = Math.abs(pendingOttava) === 2 ? 15 : 8;
+			const disPlace: 'above' | 'below' = 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
@@ -1248,9 +1286,7 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 				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
@@ -1260,9 +1296,7 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 				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);
@@ -1271,32 +1305,7 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 				flushPendingDynamics(result.elementId);
 
 				// If there's a pending ottava, start the span on this note
-				if (pendingOttava !== null && pendingOttava !== 0) {
-					const dis: 8 | 15 = Math.abs(pendingOttava) === 2 ? 15 : 8;
-					const disPlace: 'above' | 'below' = 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) {
@@ -1394,23 +1403,38 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 			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 as RestEvent, 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 as TupletEvent, 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 as Clef;
@@ -1420,7 +1444,7 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 				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.
@@ -1482,9 +1506,22 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 							}
 							currentOctave = null;
 							ottavaExplicitlyClosed = true;  // Mark that we explicitly closed the span
+						} 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 (e.g., at measure start), keep currentOctave alive
-						// It may be continued by a subsequent ottava command with the same value
+						// 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 {
 						// Check if this continues an existing span (same value)
@@ -1866,8 +1903,9 @@ const BARLINE_TO_MEI: Record<string, string> = {
 
 // Encode a measure
 // encodeMeasure accepts mutable tieState, slurState, hairpinState, ottavaState and clefState that persist across measures
-const encodeMeasure = (measure: Measure, measureN: number, indent: string, totalStaves: number, tieState: TieState, slurState: SlurState, hairpinState: HairpinState, ottavaState: OttavaState, keyFifths: number = 0, partInfos: PartInfo[] = [], clefState: ClefState = {}, octaveEndReplacements: Record<string, string> = {}): string => {
+const encodeMeasure = (measure: Measure, measureN: number, indent: string, totalStaves: number, tieState: TieState, slurState: SlurState, hairpinState: HairpinState, ottavaState: OttavaState, keyFifths: number = 0, partInfos: PartInfo[] = [], clefState: ClefState = {}, octaveEndReplacements: Record<string, string> = {}, measureIds?: string[]): string => {
 	const measureId = generateId("measure");
+	if (measureIds) measureIds.push(measureId);
 	let staffContent = '';  // Build staff content first, then add measure tag with barline
 	const allHairpins: HairpinSpan[] = [];
 	const allPedals: PedalMark[] = [];
@@ -2700,6 +2738,74 @@ const encode = (doc: LilyletDoc, options: MEIEncoderOptions = {}): string => {
 	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: string[] = [];
+
+	// 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: Measure): boolean => {
+		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: ReturnType<typeof decomposeToSegments> = null;
+	const segOpenAt = new Map<number, string>();    // measure index → opening tag for its segment
+	const segCloseAt = new Map<number, string>();   // measure index → closing tag after it
+	const segIdById = new Map<string, string>();    // 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: TieState = {};
@@ -2731,28 +2837,6 @@ const encode = (doc: LilyletDoc, options: MEIEncoderOptions = {}): string => {
 		}
 	}
 
-	// Helper to check if a measure has any musical content
-	const measureHasContent = (measure: Measure): boolean => {
-		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
@@ -2810,9 +2894,57 @@ const encode = (doc: LilyletDoc, options: MEIEncoderOptions = {}): string => {
 				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 is string => 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: string[] = [];
+			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 as Error).message}`);
+		}
+	}
+
 	mei += `${indent}${indent}${indent}${indent}${indent}</section>\n`;
 	mei += `${indent}${indent}${indent}${indent}</score>\n`;
 	mei += `${indent}${indent}${indent}</mdiv>\n`;