@k-l-lambda/lilylet 0.1.67 → 0.1.69

package/source/lilylet/lilylet.jison

@@ -127,6 +127,7 @@
 	const barlineEvent = (style) => ({ type: 'barline', style });
 	const harmonyEvent = (text) => ({ type: 'harmony', text });
 	const markupEvent = (content, placement) => ({ type: 'markup', content, placement: placement || undefined });
+	const dynamicEvent = (type) => ({ type: 'dynamic', dynamicType: type });
 	const markupMark = (content) => ({ markType: 'markup', content });
 
 	// Parse PITCH token (e.g., "c", "cs", "bf", "css", "bff") into phonet and accidental
@@ -445,6 +446,7 @@ event
 	| barline_event
 	| harmony_event
 	| markup_event
+	| dynamic_event
 	;
 
 barline_event
@@ -457,6 +459,12 @@ harmony_event
 
 markup_event
 	: CMD_MARKUP STRING							-> markupEvent($2.slice(1, -1))
+	| '^' CMD_MARKUP STRING						-> markupEvent($3.slice(1, -1), 'above')
+	| '_' CMD_MARKUP STRING						-> markupEvent($3.slice(1, -1), 'below')
+	;
+
+dynamic_event
+	: dynamic_mark								-> dynamicEvent($1.type)
 	;
 
 pitch_reset_event

package/source/lilylet/meiEncoder.ts

@@ -12,6 +12,7 @@ import {
 	BarlineEvent,
 	HarmonyEvent,
 	MarkupEvent,
+	DynamicEvent,
 	Pitch,
 	Clef,
 	Accidental,
@@ -653,9 +654,10 @@ const noteEventToMEI = (
 
 
 // Convert RestEvent to MEI
-const restEventToMEI = (event: RestEvent, indent: string, keyFifths: number = 0, ottavaShift: number = 0, measureAccidentals?: Map<string, string>, crossStaff?: number): string => {
+const restEventToMEI = (event: RestEvent, indent: string, keyFifths: number = 0, ottavaShift: number = 0, measureAccidentals?: Map<string, string>, crossStaff?: number): { xml: string; elementId: string } => {
 	const dur = DURATIONS[event.duration.division] || "4";
-	let attrs = `xml:id="${generateId('rest')}" dur="${dur}"`;
+	const restId = generateId('rest');
+	let attrs = `xml:id="${restId}" dur="${dur}"`;
 	if (event.duration.dots > 0) attrs += ` dots="${event.duration.dots}"`;
 
 	// Cross-staff attribute
@@ -669,15 +671,16 @@ const restEventToMEI = (event: RestEvent, indent: string, keyFifths: number = 0,
 
 	// Space rest (invisible)
 	if (event.invisible) {
-		return `${indent}<space ${attrs} />\n`;
+		return { xml: `${indent}<space ${attrs} />\n`, elementId: restId };
 	}
 
 	// Full measure rest
 	if (event.fullMeasure) {
-		return `${indent}<mRest xml:id="${generateId('mrest')}" />\n`;
+		const mRestId = generateId('mrest');
+		return { xml: `${indent}<mRest xml:id="${mRestId}" />\n`, elementId: mRestId };
 	}
 
-	return `${indent}<rest ${attrs} />\n`;
+	return { xml: `${indent}<rest ${attrs} />\n`, elementId: restId };
 };
 
 
@@ -784,7 +787,7 @@ const tupletEventToMEI = (event: TupletEvent, indent: string, layerStaff?: numbe
 			}
 		} else if (e.type === 'rest') {
 			const restIndent = beamOpen ? baseIndent + '    ' : baseIndent;
-			xml += restEventToMEI(e as RestEvent, restIndent, keyFifths, ottavaShift, measureAccidentals);
+			xml += restEventToMEI(e as RestEvent, restIndent, keyFifths, ottavaShift, measureAccidentals).xml;
 		} else if (e.type === 'context') {
 			const ctx = e as ContextChange;
 			if (ctx.clef && ctx.clef !== activeClef) {
@@ -1006,7 +1009,7 @@ interface LayerResult {
 
 
 // Helper: check if an event (or any note inside a tuplet) has beam start/end
-const getEventBeamMarks = (event: NoteEvent | RestEvent | TupletEvent | TimesEvent | TremoloEvent | ContextChange | BarlineEvent | HarmonyEvent | MarkupEvent | { type: 'pitchReset' }): { beamStart: boolean; beamEnd: boolean } => {
+const getEventBeamMarks = (event: NoteEvent | RestEvent | TupletEvent | TimesEvent | TremoloEvent | ContextChange | BarlineEvent | HarmonyEvent | MarkupEvent | DynamicEvent | { type: 'pitchReset' }): { beamStart: boolean; beamEnd: boolean } => {
 	if (event.type === 'note') {
 		const markOptions = extractMarkOptions((event as NoteEvent).marks);
 		return { beamStart: markOptions.beamStart, beamEnd: markOptions.beamEnd };
@@ -1079,6 +1082,7 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 	const barlines: BarlineRef[] = [];
 	const markups: MarkupRef[] = [];
 	const pendingMarkups: { content: string; placement?: 'above' | 'below' }[] = [];
+	const pendingDynamics: string[] = [];
 
 	// Track current stem direction from context changes
 	let currentStemDirection: StemDirection | undefined = undefined;
@@ -1100,6 +1104,14 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 		pendingMarkups.length = 0;
 	};
 
+	// Helper to flush pending leading dynamics onto a note ID
+	const flushPendingDynamics = (noteId: string) => {
+		for (const label of pendingDynamics) {
+			dynamics.push({ startid: noteId, label });
+		}
+		pendingDynamics.length = 0;
+	};
+
 	// Helper to check if pitches match for tie continuation
 	const pitchesMatch = (p1: Pitch[], p2: Pitch[]): boolean => {
 		if (p1.length !== p2.length) return false;
@@ -1169,6 +1181,9 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 				// 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: 8 | 15 = Math.abs(pendingOttava) === 2 ? 15 : 8;
@@ -1283,7 +1298,12 @@ 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;
-				xml += restEventToMEI(event as RestEvent, currentIndent, keyFifths, currentOttavaShift, measureAccidentals, restCrossStaff);
+				const restResult = restEventToMEI(event as RestEvent, currentIndent, keyFifths, currentOttavaShift, measureAccidentals, restCrossStaff);
+				xml += restResult.xml;
+				// 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':
@@ -1301,6 +1321,7 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 				// Flush any pending markups onto the first note of the tuplet
 				if (tupletResult.firstNoteId) {
 					flushPendingMarkups(tupletResult.firstNoteId);
+					flushPendingDynamics(tupletResult.firstNoteId);
 					lastNoteId = tupletResult.firstNoteId;
 				}
 
@@ -1416,6 +1437,13 @@ const encodeLayer = (voice: Voice, layerN: number, indent: string, initialTiePit
 				}
 			}
 				break;
+
+			case 'dynamic': {
+				// Standalone (leading) dynamic - attaches to the following note
+				const dynEvent = event as DynamicEvent;
+				pendingDynamics.push(dynEvent.dynamicType);
+			}
+				break;
 		}
 
 		// Close beam element if beam ends

package/source/lilylet/serializer.ts

@@ -18,6 +18,8 @@ import {
 	TimesEvent,
 	TremoloEvent,
 	BarlineEvent,
+	MarkupEvent,
+	DynamicEvent,
 	Pitch,
 	Duration,
 	Mark,
@@ -276,13 +278,15 @@ const serializeMarks = (marks: Mark[]): string => {
 const serializeNoteEvent = (
 	event: NoteEvent,
 	env: PitchEnv,
-	prevDuration?: Duration
+	prevDuration?: Duration,
+	suppressGracePrefix: boolean = false
 ): { str: string; newEnv: PitchEnv } => {
 	const parts: string[] = [];
 	let currentEnv = env;
 
-	// Grace note prefix
-	if (event.grace) {
+	// Grace note prefix. When the caller groups consecutive grace notes into a single
+	// scoped \grace { ... }, it suppresses the per-note prefix and emits the wrapper.
+	if (event.grace && !suppressGracePrefix) {
 		parts.push('\\grace ');
 	}
 
@@ -562,11 +566,12 @@ const serializeBarlineEvent = (event: BarlineEvent): string => {
 const serializeEvent = (
 	event: Event,
 	env: PitchEnv,
-	prevDuration?: Duration
+	prevDuration?: Duration,
+	suppressGracePrefix: boolean = false
 ): { str: string; newEnv: PitchEnv } => {
 	switch (event.type) {
 		case 'note':
-			return serializeNoteEvent(event as NoteEvent, env, prevDuration);
+			return serializeNoteEvent(event as NoteEvent, env, prevDuration, suppressGracePrefix);
 		case 'rest':
 			return serializeRestEvent(event as RestEvent, env, prevDuration);
 		case 'context':
@@ -578,6 +583,15 @@ const serializeEvent = (
 			return serializeTremoloEvent(event as TremoloEvent, env);
 		case 'barline':
 			return { str: serializeBarlineEvent(event as BarlineEvent), newEnv: env };
+		case 'markup': {
+			const mk = event as MarkupEvent;
+			const prefix = mk.placement === 'above' ? '^' : mk.placement === 'below' ? '_' : '';
+			return { str: `${prefix}\\markup "${mk.content}"`, newEnv: env };
+		}
+		case 'dynamic': {
+			const dynStr = DYNAMIC_MAP[(event as DynamicEvent).dynamicType];
+			return { str: dynStr || '', newEnv: env };
+		}
 		default:
 			return { str: '', newEnv: env };
 	}
@@ -591,8 +605,12 @@ interface MeasureContext {
 	clef?: Clef;
 }
 
-// Find first clef in voice events
+// Find the voice's leading clef: the clef in effect at the START of the voice, i.e.
+// a clef context event that appears before any musical event on the home staff.
+// A clef that first appears AFTER a note is a mid-voice change and must be emitted
+// inline where it occurs, not hoisted to the front — so it is not returned here.
 const findVoiceClef = (voice: Voice): Clef | undefined => {
+	const MUSICAL = new Set(['note', 'rest', 'tuplet', 'times', 'tremolo']);
 	let activeStaff = voice.staff;
 	for (const event of voice.events) {
 		if (event.type === 'context') {
@@ -601,6 +619,9 @@ const findVoiceClef = (voice: Voice): Clef | undefined => {
 			if (ctx.clef && activeStaff === voice.staff) {
 				return ctx.clef;
 			}
+		} else if (MUSICAL.has(event.type)) {
+			// Reached music on the home staff before any clef — no leading clef.
+			if (activeStaff === voice.staff) return undefined;
 		}
 	}
 	return undefined;
@@ -631,7 +652,6 @@ const serializeVoice = (
 	// 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++) {
@@ -653,7 +673,9 @@ const serializeVoice = (
 			leadStaffScanEnd = i + 1; // time/key/stemDir — continue scan
 			continue;
 		}
-		if (MUSICAL_TYPES.has(e.type)) break;
+		// Any other event (note/rest/tuplet/markup/dynamic/harmony/barline/…) has a
+		// visible position; a staff switch after it must not be hoisted ahead of it.
+		break;
 	}
 
 	// Output staff command if voice staff differs from current parser staff,
@@ -684,18 +706,20 @@ const serializeVoice = (
 		}
 	}
 
-	// Output clef only if not yet emitted or changed for this staff
-	const voiceClef = allStaffClefs?.[voice.staff] || findVoiceClef(voice);
+	// Output clef only if not yet emitted or changed for this staff.
+	// 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];
 	const clefAlreadyEmitted = voiceClef && emittedClefs?.[voice.staff] === voiceClef;
 	if (voiceClef && !clefAlreadyEmitted) {
 		parts.push('\\clef "' + (CLEF_MAP[voiceClef] ?? 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: StemDirection | undefined;
+	let graceGroupOpen = false;  // whether a scoped \grace { ... } is currently open
 
 	for (let eventIdx = 0; eventIdx < voice.events.length; eventIdx++) {
 		const event = voice.events[eventIdx];
@@ -719,8 +743,13 @@ const serializeVoice = (
 			}
 			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) {
+			// Skip a clef-only context event only if it is REDUNDANT — i.e. it restates the
+			// clef already active for this staff. A clef that differs is a genuine change and
+			// must be emitted inline at its position.
+			if (
+				ctx.clef && !ctx.key && !ctx.time && !ctx.ottava && !ctx.stemDirection && !ctx.tempo &&
+				emittedClefs?.[ctx.staff || activeStaff] === ctx.clef
+			) {
 				continue;
 			}
 		}
@@ -756,7 +785,19 @@ const serializeVoice = (
 			}
 		}
 
-		const { str: eventStr, newEnv } = serializeEvent(event, pitchEnv, prevDuration);
+		const isGraceNote = event.type === 'note' && !!(event as NoteEvent).grace;
+
+		// Group consecutive grace notes into one scoped \grace { ... } instead of
+		// emitting a separate \grace prefix per note.
+		if (isGraceNote && !graceGroupOpen) {
+			parts.push('\\grace {');
+			graceGroupOpen = true;
+		} else if (!isGraceNote && graceGroupOpen) {
+			parts.push('}');
+			graceGroupOpen = false;
+		}
+
+		const { str: eventStr, newEnv } = serializeEvent(event, pitchEnv, prevDuration, graceGroupOpen);
 		pitchEnv = newEnv;
 
 		if (eventStr) {
@@ -780,6 +821,11 @@ const serializeVoice = (
 		}
 	}
 
+	// Close a grace group left open at the end of the voice (unusual but possible).
+	if (graceGroupOpen) {
+		parts.push('}');
+	}
+
 	return { str: parts.join(' '), newStaff: voice.staff };
 };
 
@@ -958,26 +1004,32 @@ export const serializeLilyletDoc = (doc: LilyletDoc): string => {
 			currentTime = measure.timeSig;
 		}
 
-		// Collect clefs from this measure's voices, per part
-		measure.parts.forEach((part, pi) => {
-			const staffClefs = partStaffClefs[pi] || (partStaffClefs[pi] = {});
-			for (const voice of part.voices) {
-				let clefActiveStaff = voice.staff;
-				for (const event of voice.events) {
-					if (event.type === 'context') {
-						const ctx = event as ContextChange;
-						if (ctx.staff) {
-							clefActiveStaff = ctx.staff;
-						}
-						if (ctx.clef) {
-							staffClefs[clefActiveStaff] = ctx.clef;
+		// Collect clefs from this measure's voices, per part — but only AFTER serializing
+		// the measure, so that during serialization allStaffClefs reflects the clef state
+		// CARRIED IN from previous measures (a mid-measure clef change must not be hoisted
+		// to the measure's front; it is emitted inline at its position).
+		const collectClefs = () => {
+			measure.parts.forEach((part, pi) => {
+				const staffClefs = partStaffClefs[pi] || (partStaffClefs[pi] = {});
+				for (const voice of part.voices) {
+					let clefActiveStaff = voice.staff;
+					for (const event of voice.events) {
+						if (event.type === 'context') {
+							const ctx = event as ContextChange;
+							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, partStaffClefs, partEmittedClefs);
+		collectClefs();
 		// Always include measure, even if empty (use space rest for empty measures)
 		measureStrs.push(measureStr || 's1');
 		currentStaff = newStaff;

package/source/lilylet/types.ts

@@ -278,7 +278,12 @@ export interface MarkupEvent {
 	placement?: Placement;  // Optional placement (above/below)
 }
 
-export type Event = NoteEvent | RestEvent | ContextChange | TremoloEvent | TupletEvent | TimesEvent | PitchResetEvent | BarlineEvent | HarmonyEvent | MarkupEvent;
+export interface DynamicEvent {
+	type: 'dynamic';
+	dynamicType: DynamicType;  // Standalone dynamic at a leading position (before any note)
+}
+
+export type Event = NoteEvent | RestEvent | ContextChange | TremoloEvent | TupletEvent | TimesEvent | PitchResetEvent | BarlineEvent | HarmonyEvent | MarkupEvent | DynamicEvent;
 
 // === Structure ===