@k-l-lambda/lilylet 0.1.74 → 0.1.76

package/source/lilylet/musicXmlDecoder.ts

@@ -69,6 +69,7 @@ import {
 	createFraction,
 	TYPE_TO_DIVISION,
 } from './musicXmlUtils';
+import { measureLayoutFromPart } from './measureLayoutFromXml';
 
 // ============ Spanner Tracker ============
 
@@ -630,6 +631,25 @@ const parseDirection = (dirEl: Element): MusicXmlDirection => {
 	result.placement = getAttribute(dirEl, 'placement') as 'above' | 'below' | undefined;
 	result.staff = getElementInt(dirEl, 'staff');
 
+	// Navigation jumps live on the <sound> child of <direction> (a sibling of
+	// <direction-type>). Parse it first, before the no-direction-type early return,
+	// so a sound-only direction still contributes its jump semantics.
+	const soundEl = dirEl.getElementsByTagName('sound')[0];
+	if (soundEl) {
+		const sound: NonNullable<MusicXmlDirection['sound']> = {};
+		if (getAttribute(soundEl, 'dacapo') === 'yes') sound.dacapo = true;
+		if (getAttribute(soundEl, 'fine') === 'yes') sound.fine = true;
+		const dalsegno = getAttribute(soundEl, 'dalsegno');
+		if (dalsegno) sound.dalsegno = dalsegno;
+		const segno = getAttribute(soundEl, 'segno');
+		if (segno) sound.segno = segno;
+		const coda = getAttribute(soundEl, 'coda');
+		if (coda) sound.coda = coda;
+		const tocoda = getAttribute(soundEl, 'tocoda');
+		if (tocoda) sound.tocoda = tocoda;
+		if (Object.keys(sound).length > 0) result.sound = sound;
+	}
+
 	const dirTypeEl = dirEl.getElementsByTagName('direction-type')[0];
 	if (!dirTypeEl) {
 		return result;
@@ -722,7 +742,8 @@ const parseBarline = (barlineEl: Element): MusicXmlBarline => {
 	if (repeatEl) {
 		const direction = getAttribute(repeatEl, 'direction') as 'forward' | 'backward';
 		if (direction) {
-			result.repeat = { direction };
+			const times = getAttributeNumber(repeatEl, 'times');
+			result.repeat = times !== undefined ? { direction, times } : { direction };
 		}
 	}
 
@@ -1065,7 +1086,10 @@ const directionToMarks = (
 	// Tempo words ("Allegro", "a tempo", ...) are consumed separately as a tempo
 	// ContextChange by directionToContextChange, so skip those here to avoid
 	// double-emitting; everything else becomes a markup mark → MEI <dir>. Metronome
-	// directions are tempo too, never markup.
+	// directions are tempo too, never markup. Navigation text ("D.C. al Fine",
+	// "To Coda", "Fine", "D.S. al Coda") is NOT a tempo word, so it flows here as a
+	// markup glyph — the jump SEMANTICS are captured separately as measure-layout.
+	let emittedWords = false;
 	if (direction.words && direction.words.length > 0 && !direction.metronome) {
 		const text = direction.words.map(w => w.text).join('').trim();
 		if (text && !isTempoWord(text)) {
@@ -1073,6 +1097,27 @@ const directionToMarks = (
 				: direction.placement === 'below' ? Placement.below
 				: undefined;
 			marks.push({ markType: 'markup', content: text, placement });
+			emittedWords = true;
+		}
+	}
+
+	// A <sound> navigation with NO visible <words> (e.g. a bare <sound tocoda=>):
+	// synthesize the conventional glyph text so the score still shows the marking.
+	// Segno/coda GLYPHS (the symbols, via <direction-type><segno|coda>) are already
+	// emitted above as NavigationMark; only the textual D.C./D.S./Fine/To-Coda need
+	// synthesizing, and only when the engraver left them implicit.
+	if (!emittedWords && direction.sound && !direction.coda && !direction.segno) {
+		const s = direction.sound;
+		const label = s.dacapo ? (s.fine ? 'D.C. al Fine' : 'D.C.')
+			: s.dalsegno ? (s.fine ? 'D.S. al Fine' : 'D.S. al Coda')
+			: s.tocoda ? 'To Coda'
+			: s.fine ? 'Fine'
+			: undefined;
+		if (label) {
+			const placement = direction.placement === 'above' ? Placement.above
+				: direction.placement === 'below' ? Placement.below
+				: undefined;
+			marks.push({ markType: 'markup', content: label, placement });
 		}
 	}
 
@@ -1087,6 +1132,12 @@ interface MeasureConversionResult {
 	key?: KeySignature;
 	timeSig?: Fraction;
 	barline?: BarlineEvent;
+	// A `location="left"` repeat (e.g. forward-repeat `.|:`) belongs at the FRONT
+	// of this measure, but lilylet models a `\bar` as the END bar of its measure.
+	// So it is carried back onto the PREVIOUS measure's trailing barline by
+	// convertPart (dropped if this is the first measure — a leading `|:` at the
+	// very start of the piece is conventionally omitted).
+	leadingBarline?: BarlineEvent;
 	harmonies: HarmonyEvent[];
 	clefs: Map<number, ContextChange>;  // staff number → clef context
 }
@@ -1149,6 +1200,7 @@ const convertMeasure = (
 	let key: KeySignature | undefined;
 	let timeSig: Fraction | undefined;
 	let barline: BarlineEvent | undefined;
+	let leadingBarline: BarlineEvent | undefined;
 	const harmonies: HarmonyEvent[] = [];
 	const clefs: Map<number, ContextChange> = new Map();
 
@@ -1166,6 +1218,15 @@ const convertMeasure = (
 	// layer (otherwise the encoder can't pair them and drops the span).
 	const pendingContextChanges: { ctx: ContextChange; staff?: number }[] = [];
 	let currentVoice = 1;  // Track current voice for directions
+	// Mid-measure clef support: a staff can change clef partway through a measure
+	// (common in scale/arpeggio études where the LH crosses up). Such a clef arrives
+	// in an <attributes> block AFTER notes on that staff. We must attach it inline at
+	// that point on the staff's currently-active voice, not collapse it into the
+	// measure-start `clefs` map (which keeps only one clef per staff and emits it at
+	// the bar start). Track the last voice that added a note on each staff, and which
+	// staves already have notes this measure.
+	const lastVoiceOnStaff: Map<number, number> = new Map();
+	const staffHasNotes: Set<number> = new Set();
 
 	// Process all children in order
 	for (const child of getChildElements(measureEl)) {
@@ -1197,7 +1258,30 @@ const convertMeasure = (
 				for (const clefEntry of attrs.clefs) {
 					const clef = convertClef(clefEntry.clef.sign, clefEntry.clef.line);
 					if (clef) {
-						clefs.set(clefEntry.staff, { type: 'context', clef });
+						const staff = clefEntry.staff;
+						if (staffHasNotes.has(staff)) {
+							// Mid-measure clef change: this staff already has notes in this
+							// measure, so the clef takes effect HERE, not at the bar start.
+							// Append it inline on the staff's currently-active voice via
+							// addEvent (which inserts a staff-switch context if that voice is
+							// currently positioned on another staff — e.g. a cross-staff
+							// voice — so the clef binds to `staff`, not the voice's current
+							// staff). Zero duration: a clef does not advance time.
+							const vNum = lastVoiceOnStaff.get(staff);
+							if (vNum !== undefined) {
+								// Tag the clef context with its staff explicitly. In a
+								// cross-staff voice (where notes interleave staves) a bare
+								// clef is ambiguous and is dropped/misplaced by the serializer;
+								// the explicit staff makes it self-describing (serializer emits
+								// `\staff "N" \clef ...`). addEvent still inserts a leading
+								// staff switch when the voice is currently on another staff.
+								voiceTracker.addEvent(vNum, { type: 'context', staff, clef } as ContextChange, 0, staff);
+							} else {
+								clefs.set(staff, { type: 'context', clef });
+							}
+						} else {
+							clefs.set(staff, { type: 'context', clef });
+						}
 					}
 				}
 			}
@@ -1206,6 +1290,10 @@ const convertMeasure = (
 			const voiceNum = note.voice;
 			const staffNum = note.staff || 1;
 			currentVoice = voiceNum;
+			// Record that this staff now has notes this measure and which voice is
+			// active on it, so a subsequent mid-measure <clef> attaches inline here.
+			staffHasNotes.add(staffNum);
+			lastVoiceOnStaff.set(staffNum, voiceNum);
 
 			// Ensure voice exists with correct staff tracking (needed for cross-staff tuplets
 			// where notes go to tupletTracker but voice must be initialized for staff detection)
@@ -1412,7 +1500,14 @@ const convertMeasure = (
 			const barlineData = parseBarline(child);
 			const style = convertBarlineStyle(barlineData.barStyle, barlineData.repeat?.direction);
 			if (style && style !== '|') {
-				barline = { type: 'barline', style };
+				// A `location="left"` barline (forward repeat at the measure front)
+				// is carried back onto the previous measure's end bar by convertPart;
+				// everything else is this measure's own trailing end bar.
+				if (barlineData.location === 'left') {
+					leadingBarline = { type: 'barline', style };
+				} else {
+					barline = { type: 'barline', style };
+				}
 			}
 		} else if (tagName === 'harmony') {
 			const harmonyData = parseHarmony(child);
@@ -1506,7 +1601,7 @@ const convertMeasure = (
 		});
 	}
 
-	return { voiceMap, key, timeSig, barline, harmonies, clefs };
+	return { voiceMap, key, timeSig, barline, leadingBarline, harmonies, clefs };
 };
 
 /**
@@ -1524,12 +1619,30 @@ const convertPart = (partEl: Element): { measures: Measure[]; name?: string } =>
 	let isFirstMeasure = true;
 	let lastVoiceStaff = 1;  // Track last known primary voice staff for empty measure fallback
 	const lastClefs: Map<number, ContextChange> = new Map();  // Track last clef per staff
+	// Initial clef per staff declared in the FIRST <attributes> block. A staff whose
+	// first voice does not appear until a later measure (e.g. an accompaniment staff
+	// silent for the opening bars) would otherwise lose its initial clef — it is only
+	// declared in measure 1's attributes, where that staff has no voice to attach it
+	// to. We hold these and flush each onto the staff's FIRST appearing voice.
+	const pendingInitialClefs: Map<number, ContextChange> = new Map();
 
 	const measureEls = getDirectChildren(partEl, 'measure');
 
 	for (const measureEl of measureEls) {
 		voiceTracker.reset();
-		const { voiceMap, key, timeSig, barline, harmonies, clefs } = convertMeasure(measureEl, voiceTracker, spannerTracker, ottavaTracker, tupletTracker);
+		const { voiceMap, key, timeSig, barline, leadingBarline, harmonies, clefs } = convertMeasure(measureEl, voiceTracker, spannerTracker, ottavaTracker, tupletTracker);
+
+		// A forward-repeat (or any `location="left"`) barline belongs at the END of
+		// the PREVIOUS measure in lilylet's "\bar = current measure's end bar" model.
+		// Append it to the previous measure's first voice; if this is the first
+		// measure there is no previous one, so a leading repeat at the very start of
+		// the piece is conventionally dropped.
+		if (leadingBarline && measures.length > 0) {
+			const prevVoices = measures[measures.length - 1].parts[0]?.voices;
+			if (prevVoices && prevVoices.length > 0) {
+				prevVoices[0].events.push(leadingBarline);
+			}
+		}
 
 		// Update running key/time
 		if (key) lastKey = key;
@@ -1566,6 +1679,22 @@ const convertPart = (partEl: Element): { measures: Measure[]; name?: string } =>
 							lastClefs.set(voiceData.staff, clef);
 						}
 					}
+					pendingInitialClefs.delete(voiceData.staff);
+				} else if (pendingInitialClefs.has(voiceData.staff)) {
+					// This staff's clef was declared in an earlier measure where the staff
+					// had no voice to carry it (its first appearance is delayed, or it is
+					// an intermittently-empty cross-staff passage). This measure declares
+					// no clef of its own — emit the carried-forward pending clef if it
+					// differs from the clef last in effect for this staff.
+					const pending = pendingInitialClefs.get(voiceData.staff)!;
+					const lastClef = lastClefs.get(voiceData.staff);
+					const isSameClef = lastClef &&
+						(lastClef as ContextChange).clef === (pending as ContextChange).clef;
+					if (!isSameClef) {
+						events.push(pending);
+						lastClefs.set(voiceData.staff, pending);
+					}
+					pendingInitialClefs.delete(voiceData.staff);
 				}
 				staffsWithClef.add(voiceData.staff);
 			}
@@ -1573,6 +1702,22 @@ const convertPart = (partEl: Element): { measures: Measure[]; name?: string } =>
 			// Add voice events
 			events.push(...voiceData.events);
 
+			// A mid-measure clef change was appended inline to this voice's events (it
+			// does not pass through the measure-start `clefs` map). Scan for the LAST
+			// clef per staff in this voice and update lastClefs, so the next measure's
+			// dedup compares against the clef actually in effect — otherwise a later
+			// measure restating the pre-change clef would be wrongly suppressed.
+			{
+				let scanStaff = voiceData.staff;
+				for (const ev of voiceData.events) {
+					if (ev.type === 'context') {
+						const c = ev as ContextChange;
+						if (c.staff != null) scanStaff = c.staff;
+						if (c.clef) lastClefs.set(scanStaff, { type: 'context', clef: c.clef });
+					}
+				}
+			}
+
 			// Add harmonies and barline to first voice only
 			if (voiceNum === voiceNumbers[0]) {
 				for (const h of harmonies) {
@@ -1596,6 +1741,16 @@ const convertPart = (partEl: Element): { measures: Measure[]; name?: string } =>
 			lastVoiceStaff = voices[0].staff || 1;
 		}
 
+		// Carry forward any clef declared this measure for a staff that had NO voice to
+		// attach it to (an intermittently-empty staff — e.g. cross-staff passages where
+		// the LH is written entirely on the upper staff for several bars). Remember it
+		// as pending so it is emitted when that staff next reappears; otherwise the clef
+		// (and any change it represents) is lost when this measure's `clefs` map is
+		// discarded. Generalizes the first-measure seeding above to every measure.
+		for (const [staff, clef] of clefs) {
+			if (!staffsWithClef.has(staff)) pendingInitialClefs.set(staff, clef);
+		}
+
 		const measure: Measure = {
 			parts: [{
 				voices,
@@ -1730,6 +1885,14 @@ export const decode = (input: string | Uint8Array): LilyletDoc => {
 		measures: mergedMeasures,
 	};
 
+	// Derive the performance order (repeats / voltas / D.C. / D.S. / Coda / Fine)
+	// from the first part's barline + <sound> navigation markup → measure-layout
+	// string. The MEI encoder turns this into an <expansion> that verovio unfolds
+	// for MIDI. Repeat markup is part-global; the first part carries it. Never
+	// throws (returns undefined when there is nothing to unfold).
+	const measureLayout = measureLayoutFromPart(partEls[0]);
+	if (measureLayout) metadata.measureLayout = measureLayout;
+
 	if (Object.keys(metadata).length > 0) {
 		result.metadata = metadata;
 	}

package/source/lilylet/musicXmlTypes.ts

@@ -124,6 +124,17 @@ export interface MusicXmlDirection {
 	octaveShift?: MusicXmlOctaveShift;
 	coda?: boolean;
 	segno?: boolean;
+	// Navigation jumps from the <sound> sibling inside <direction>. Present when
+	// the score carries D.C./D.S./Coda/Fine playback semantics; drives the
+	// performance-order (measure-layout) derivation, not a notational glyph.
+	sound?: {
+		dacapo?: boolean;          // <sound dacapo="yes"> — da capo
+		dalsegno?: string;         // <sound dalsegno="N"> — dal segno (target segno id)
+		segno?: string;            // <sound segno="N"> — marks a segno point
+		coda?: string;             // <sound coda="N"> — marks a coda point
+		tocoda?: string;           // <sound tocoda="N"> — "to coda" jump
+		fine?: boolean;            // <sound fine="yes"> — Fine (stop point on D.C./D.S.)
+	};
 }
 
 // ============ Barline Types ============
@@ -133,6 +144,7 @@ export interface MusicXmlBarline {
 	barStyle?: string;          // regular, light-light, light-heavy, heavy-light, heavy-heavy, etc.
 	repeat?: {
 		direction: 'forward' | 'backward';
+		times?: number;          // <repeat times="N"> — repeat count (default 2 for backward)
 	};
 	ending?: {
 		type: 'start' | 'stop' | 'discontinue';

package/source/lilylet/serializer.ts

@@ -36,6 +36,40 @@ import {
 	Placement,
 	Metadata,
 } from "./types";
+import { parseMeasureLayout, MeasureLayout } from "./measureLayout";
+
+
+// Walk a measure-layout AST, recording the FIRST measure index of each alternate
+// ending (1st/2nd house) → its ending number, for the `% volta N` serializer
+// comment convention. Only the alternates of a VoltaMLayout produce labels.
+const collectVoltaLabels = (layout: MeasureLayout, out: Map<number, number>): void => {
+	const firstIndexOf = (node: MeasureLayout): number | undefined => {
+		switch (node.kind) {
+		case "single": return node.measure;
+		case "block": return node.seq.length ? firstIndexOf(node.seq[0]) : undefined;
+		case "volta": return node.body.length ? firstIndexOf(node.body[0]) : undefined;
+		case "aba": return firstIndexOf(node.main);
+		}
+	};
+	const walk = (node: MeasureLayout): void => {
+		switch (node.kind) {
+		case "block": node.seq.forEach(walk); break;
+		case "aba": walk(node.main); node.rest.forEach(walk); break;
+		case "volta":
+			node.body.forEach(walk);
+			if (node.alternates) {
+				node.alternates.forEach((alt, ai) => {
+					const first = alt.length ? firstIndexOf(alt[0]) : undefined;
+					if (first !== undefined && !out.has(first)) out.set(first, ai + 1);
+					alt.forEach(walk);
+				});
+			}
+			break;
+		default: break;
+		}
+	};
+	walk(layout);
+};
 
 
 const PHONETS = "cdefgab";
@@ -483,9 +517,20 @@ const serializeTupletEvent = (
 			prevDuration = (e as RestEvent).duration;
 		} else if (e.type === 'context') {
 			const ctx = e as ContextChange;
+			// A context event inside a tuplet may carry several components at once
+			// (e.g. staff + clef). Emit each present one — previously only staff and
+			// stemDirection were handled, so a clef/ottava change inside a tuplet was
+			// silently dropped on serialization.
 			if (ctx.staff != null) {
 				parts.push(' \\staff "' + ctx.staff + '"');
-			} else if (ctx.stemDirection != null) {
+			}
+			if (ctx.clef != null) {
+				parts.push(' \\clef "' + (CLEF_MAP[ctx.clef] ?? ctx.clef) + '"');
+			}
+			if (ctx.ottava != null) {
+				parts.push(' \\ottava #' + ctx.ottava);
+			}
+			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');
@@ -586,7 +631,7 @@ const serializeEvent = (
 		case 'markup': {
 			const mk = event as MarkupEvent;
 			const prefix = mk.placement === 'above' ? '^' : mk.placement === 'below' ? '_' : '';
-			return { str: `${prefix}\\markup "${mk.content}"`, newEnv: env };
+			return { str: `${prefix}\\markup "${escapeString(mk.content)}"`, newEnv: env };
 		}
 		case 'dynamic': {
 			const dynStr = DYNAMIC_MAP[(event as DynamicEvent).dynamicType];
@@ -654,6 +699,28 @@ const serializeVoice = (
 	// context{staff} events before this index are skipped in the main loop.
 	let effectiveInitialStaff = voice.staff;
 	let leadStaffScanEnd = 0;
+	// Staff of the first MUSICAL event (note/rest/...), honouring an explicit
+	// note.staff. If it differs from the home staff, the first inline staff switch
+	// would emit a `\staff "X"` that the parser mistakes for the LEADING staff (it
+	// binds home to the first `\staff` before any music), relocating the voice and
+	// any leading clef. We then force an explicit home-staff anchor up front. This
+	// scan is independent of leadStaffScanEnd because a leading clef/key stops that
+	// scan before the first note is reached.
+	let firstMusicalStaff: number | null = null;
+	{
+		let scanStaff = voice.staff;
+		for (const e of voice.events) {
+			if (e.type === 'context') {
+				const ctx = e as ContextChange;
+				if (ctx.staff != null) scanStaff = ctx.staff;
+				continue;
+			}
+			if (e.type === 'pitchReset') continue;
+			if (e.type === 'note') firstMusicalStaff = (e as NoteEvent).staff ?? scanStaff;
+			else firstMusicalStaff = scanStaff;
+			break;
+		}
+	}
 	for (let i = 0; i < voice.events.length; i++) {
 		const e = voice.events[i];
 		if (e.type === 'pitchReset') { leadStaffScanEnd = i + 1; continue; }
@@ -678,10 +745,19 @@ const serializeVoice = (
 		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) {
+	// Output staff command if the voice's initial staff is not what the PARSER will
+	// assume. The parser (lilylet.jison voice()) assigns every voice with no leading
+	// `\staff` directive to staff 1 unconditionally — it does NOT carry staff across
+	// voices or measures. So we must emit `\staff "N"` whenever effectiveInitialStaff
+	// is not 1, even if the cross-measure carry (currentStaff) happens to match it
+	// (e.g. a whole measure sitting on staff 2 after a prior staff-2 measure — without
+	// this, the round-trip would silently relocate that voice, and its leading clef,
+	// to staff 1). Also emit when it differs from the carry (resets after grand staff)
+	// or always in a grand-staff part for clarity. Finally, force an anchor when the
+	// first note switches staff via note.staff (otherwise that inline `\staff` would
+	// be read as the leading staff and rebind the voice's home).
+	const firstNoteSwitches = firstMusicalStaff != null && firstMusicalStaff !== effectiveInitialStaff;
+	if (isGrandStaff || effectiveInitialStaff !== 1 || effectiveInitialStaff !== currentStaff || firstNoteSwitches) {
 		parts.push('\\staff "' + effectiveInitialStaff + '"');
 	}
 
@@ -710,7 +786,17 @@ const serializeVoice = (
 	// Prefer this voice's leading clef (a clef before any music); fall back to the
 	// carry-in clef from previous measures. A clef that first appears mid-voice is NOT
 	// hoisted here — it is emitted inline at its position.
-	const voiceClef = findVoiceClef(voice) ?? allStaffClefs?.[voice.staff];
+	//
+	// The carry-in fallback (`allStaffClefs[staff]`) is the clef state at the START of
+	// the measure and is NOT updated mid-measure, whereas `emittedClefs` IS. So a voice
+	// with no clef of its own must only use the fallback to ESTABLISH a staff that has
+	// not been emitted yet — never to "restate" it once any sibling voice has already
+	// emitted/changed this staff's clef this measure, because the fallback would then be
+	// stale and would wrongly revert that sibling's change (e.g. v1 moves staff 2 to
+	// treble, then v2 with no clef must not re-emit the carried-in bass).
+	const ownClef = findVoiceClef(voice);
+	const carryClef = allStaffClefs?.[voice.staff];
+	const voiceClef = ownClef ?? (emittedClefs?.[voice.staff] === undefined ? carryClef : undefined);
 	const clefAlreadyEmitted = voiceClef && emittedClefs?.[voice.staff] === voiceClef;
 	if (voiceClef && !clefAlreadyEmitted) {
 		parts.push('\\clef "' + (CLEF_MAP[voiceClef] ?? voiceClef) + '"');
@@ -734,7 +820,8 @@ const serializeVoice = (
 				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];
+				const ctxClef = ctx.clef ||
+					(emittedClefs?.[activeStaff] === undefined ? allStaffClefs?.[activeStaff] : undefined);
 				if (ctxClef && emittedClefs?.[activeStaff] !== ctxClef) {
 					parts.push('\\clef "' + (CLEF_MAP[ctxClef] ?? ctxClef) + '"');
 					if (emittedClefs) emittedClefs[activeStaff] = ctxClef;
@@ -763,7 +850,8 @@ const serializeVoice = (
 				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];
+				const targetClef =
+					emittedClefs?.[activeStaff] === undefined ? allStaffClefs?.[activeStaff] : undefined;
 				if (targetClef && emittedClefs?.[activeStaff] !== targetClef) {
 					parts.push('\\clef "' + (CLEF_MAP[targetClef] ?? targetClef) + '"');
 					if (emittedClefs) emittedClefs[activeStaff] = targetClef;
@@ -923,7 +1011,12 @@ const serializeMeasure = (
 
 // Escape string for serialization (quotes and backslashes)
 const escapeString = (str: string): string => {
-	return str.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+	return str
+		.replace(/\\/g, '\\\\')
+		.replace(/"/g, '\\"')
+		.replace(/\n/g, '\\n')
+		.replace(/\r/g, '\\r')
+		.replace(/\t/g, '\\t');
 };
 
 // Serialize metadata
@@ -954,6 +1047,9 @@ const serializeMetadata = (metadata: Metadata): string => {
 	if (metadata.staves) {
 		lines.push('[staves "' + escapeString(metadata.staves) + '"]');
 	}
+	if (metadata.measureLayout) {
+		lines.push('[measures "' + escapeString(metadata.measureLayout) + '"]');
+	}
 	if (metadata.instruments) {
 		for (const [key, instr] of Object.entries(metadata.instruments)) {
 			let line = '[instrument-' + key + ' "' + escapeString(instr.name) + '"';
@@ -1048,9 +1144,26 @@ export const serializeLilyletDoc = (doc: LilyletDoc): string => {
 		currentStaff = newStaff;
 	}
 
-	// Join measures with bar, measure number comment, and double newline
+	// Volta house-label comments (non-binding convention, like the `% n` measure
+	// index): if a measure-layout directive is present, mark the first measure of
+	// each alternate ending with a `% volta N` comment. Derived from the layout
+	// AST; purely cosmetic, never parsed back.
+	const voltaLabels = new Map<number, number>();  // 1-based measure index → ending number
+	if (doc.metadata?.measureLayout) {
+		try {
+			const layout = parseMeasureLayout(doc.metadata.measureLayout);
+			collectVoltaLabels(layout, voltaLabels);
+		} catch { /* ignore malformed layout */ }
+	}
+
+	// Join measures with bar, measure number comment, and double newline. A
+	// `% volta N` label (if any) is prepended on its own line before the measure.
 	const measuresOutput = measureStrs
-		.map((m, i) => m + ' | %' + (i + 1))
+		.map((m, i) => {
+			const label = voltaLabels.get(i + 1);
+			const prefix = label !== undefined ? '% volta ' + label + '\n' : '';
+			return prefix + m + ' | %' + (i + 1);
+		})
 		.join('\n\n');
 	parts.push(measuresOutput);
 

package/source/lilylet/types.ts

@@ -304,6 +304,10 @@ export interface Metadata {
 	instrument?: string;
 	genre?: string;
 	staves?: string;				// Raw staff-layout code, e.g. "<[v1-v2].va> {pl-pr} <b>"
+	// Raw measure-layout (performance/repeat order) DSL, lotus-style, e.g.
+	// "2*[1..8]{9,10}, 11..16" (index-wise) or "s: 4 <2 6> 2" (segment-wise).
+	// Stored verbatim; parsing/expansion to MEI <expansion> is a later phase.
+	measureLayout?: string;
 	// Per-staff / per-group instrument names, keyed by staff-layout group key (a single
 	// staff id like "1"/"v1", or a range like "1-2"/"pl-pr"). Declared via the
 	// [instrument-<key> "Name" "Short"] header. Maps to MEI <label>/<labelAbbr>.